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A  GENERIC  PREFERENCE  SYSTEM 


Section  1 :  Introduction 

Most  applications  require  user  configurable  settings.  For  example,  users 
often  want  to  specify  values  such  as  default  save  directory  path,  the  user’s  name, 
default  window  sizes,  application  flags,  etc.  The  goal  of  this  report  is  to  define  a 
design  pattern  along  with  a  C++  implementation  to  satisfy  the  recurring  need  for 
a  preference  system.  Before  explaining  the  preference  pattern  and  C++ 
implementation,  a  more  thorough  understanding  of  the  application  user’s  and 
software  engineer’s  requirements  is  needed.  These  requirements  will  help  to 
define  exactly  what  is  meant  by  the  phrase  “a  preference  system." 

Users  Requirements 

Application  users  are  usually  not  concerned  about  implementation  of  a 
preference  system  but  rather  the  functionality  that  it  provides  them.  Users 
require  that  they  can  easily  edit  individual  preferences,  or  properties.  They  also 
want  a  friendly  user  interface  that  reasonably  groups  and  describes  the 
properties.  These  changes  are  generally  expected  to  be  persistent.  In  many 
cases,  an  application  user  would  also  like  to  change  preferences  for  an 
application  without  having  to  actually  use  the  application.  Changing  preferences 
independent  of  the  application  is  helpful  for  reasons  such  as  speed,  support,  and 
solving  problems  with  the  preferences  that  maybe  having  adverse  effects  on  the 
application. 

Engineers  Requirements 

Software  engineers  are  concerned  about  effects  of  the  preference  system 
on  the  overall  design  of  the  application,  difficulty  and  speed  of  implementation, 
readability,  and  ease  of  debugging.  Software  engineers  want  a  system  that  will 
minimize  repetitious  redesigning  and  rewriting  of  common  code  across 
applications.  Although  they  do  not  want  to  write  repetitious  code,  software 
engineers  still  want  flexibility  for  each  application  domain.  Specifically  an 
individual  application  may  need  some  customizations  in  displaying  the  GUI.  The 

_  I 
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preference  file  format  also  may  change  among  each  application.  The  software 
engineer  must  also  be  guaranteed  type  safety  when  loading  information  or 
accepting  information  from  a  user  to  maintain  application  stability 

Report  Overview 

The  preference  system  we  created  satisfies  both  the  application  users’ 
functionality  requirements  and  the  software  engineers’  implementation  and 
impact  requirement. 

This  report  is  split  up  into  two  main  sections:  the  Preference  Pattern  and 
C++  Implementation  of  the  Preference  pattern’. 

Section  2:  Preference  pattern  will  describe  the  preference  system  design 
pattern,  pattern  applicability,  use  of  the  preference  system,  its  structure, 
participant  descriptions,  participant  collaboration,  and  consequences  of  the 
preference  system. 

Section  3:  C++  Implementation  of  Preference  Pattern  details  C++ 
implementation  issues  and  possible  solutions  for  the  preference  system. 

The  Appendix  section  contains  a  partial  code  listing  for  the  Special 
Projects  Group’s  implementation  of  this  preference  system,  including  a  generic 
editor  widget  for  the  preference  files.  It  also  contains  contact  information  to 
request  the  entire  library. 

Formatting  Conventions 

Throughout  this  report,  the  following  format  or  style  conventions  are  used. 

•  Class  and  function  names  are  signified  by  a  special  font  such  as  Class  Name. 

•  Class  diagrams  follow  the  Unified  Modeling  Language  format  and  syntax. 

•  Referenced  section  headings  will  be  shown  in  italics. 


'  The  format  of  the  pattern  and  implementation  sections  use  the  same  general  outline  as  patterns  presented 
in  Design  Patterns:  Elements  of  Object-Oriented  Software. 
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Section  2:  Preference  Pattern 


The  subsections  covered  are  Applicability,  Using  the  Preference  Pattern, 

Structure,  Participant  Collaborations,  Consequences,  and  Pattern  Remarks. 

•  The  Applicability  subsection  describes  and  summarizes  when  to  use  the 
preference  pattern. 

•  The  Using  the  Preference  Pattern  subsection  provides  an  overview  of  how 
the  users  of  the  completed  library  would  use  the  library  to  meet  an 
individual  application’s  needs. 

•  The  Structure  subsection  provides  UML  diagrams  describing  the  classes, 
or  participants,  in  implementing  the  pattern. 

•  The  Participant  Descriptions  subsection  compliments  the  diagrams  with  a 
description  of  the  overall  purpose  of  the  main  classes. 

•  The  Participant  Collaborations  subsection  describe  how  the  classes  in  the 
pattern  work  together. 

•  The  Consequences  subsection  describes  possible  benefits  and  liabilities 
of  the  design  pattern. 

•  The  Pattern  Remarks  subsection  describes  how  the  preference  pattern  is 
actually  composed  of  several  basic  patterns. 

Applicability 

Use  the  preference  pattern  to; 

•  Generically  be  able  to  create,  edit  and  save  a  set  of  properties.  Properties 
are  simple  types  of  information  such  as  string,  integer,  and  date. 

•  Guarantee  type  safety  in  editing  and  loading  of  properties. 

•  Save  into  user  defined  formats  such  as  plain  text,  XML  or  binary. 

•  Allow  for  different  conversion  formats  i.e.  simple  text,  SQL. 

•  Organize  properties  into  groups  and  subgroups. 

•  Create  a  graphical  user  interface  (GUI)  to  edit  and  browse  categorized 
preferences. 
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Using  the  Preference  Pattern 

Once  the  preference  pattern  has  been  implemented,  using  the  preference  library 
is  a  relatively  simple  task.  The  pattern  can  be  used  to  store  and  retrieve 
preferences,  create  a  GUI  editor,  and  serialize  the  preferences^. 

Storing  and  Retrieving  Preferences 

All  storage  and  retrieval  functionality  is  provided  in  a  class  called  Prefs. 
The  Prefs  class  has  two  main  methods  for  storage  and  retrieval;  setQand  get(). 

The  set()  method  stores  a  preference  into  the  class  by  associating  the 
preference  value  with  a  variable  name.  The  preference  values  can  also  be 
categorized  by  passing  a  group  name  into  the  set()  method  as  well.  A  C-f  -r  code 
example  of  how  to  set  values  may  look  like: 

//  create  the  preference  object 
Prefs  prefs; 

//  store  1000  into  a  variable  “maxWidth”  in  group  Windows 
prefs.set(“maxWidth”,  1000,  type_id(int),  “Windows”,  “Maximum  width  of  a 
window”); 

//  store  “”  into  a  variable  “userName”  in  group  Personal 
prefs.set(“userName”,  std::string(“”),  type_id(std;;string),  “Personal”,  “User 
name"); 

In  this  simple  example,  a  Prefs  object  is  created  and  two  variables  are  stored  in 
the  object.  The  parameters  passed  to  the  set()  method  are  variable  name,  value, 
type  information,  group  name,  and  description.  Don’t  worry  about  type 
information  for  now  since  it  is  a  C++  implementation  issue. 

The  get()  method  can  be  used  to  retrieve  the  preference.  The  get() 
method  takes  the  name  of  the  variable,  the  destination  variable,  type  information 
and  the  group  as  parameters.  A  C++  code  example  that  builds  upon  the 
example  above  may  look  like: 
int  width; 

QString  userName; 

//  retrieve  the  value  associated  with  “maxWidth”  into  width 
prefs.getfmaxWidth”,  width,  typejd(int),  “Windows”); 
prefs.get(“userName”,  userName,  typeJd(QString),  “Personal”); 


^  Serialization  is  the  process  of  saving  and  loading  of  an  object. 
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GUI  Editor  and  Serialization 

Creating  a  graphical  preference  editor  and  serializing  the  Prefs  class  can 
be  accomplished  with  a  few  method  calls.  The  preference  editor  in  the  example 
below  is  a  dialog  that  takes  the  preference  class.  The  code  to  show  the  editor 
could  be  as  simple  as: 

Prefs  prefs; 

//  preference  items  have  been  initialized 
PrefsEditorDialog  dialog(prefs,  parentWindow); 
dialog.showO: 

The  dialog  will  edit  the  preferences  generically.  This  dialog  could  be  used  inside 
an  application  or  could  in  fact  become  its  own  application. 

The  Prefs  class  serialization  is  almost  as  simple.  There  is  a  class  called 
PrefsSerializerRegistry  that  allows  the  specification  of  multiple  file  formats.  The 
PrefsSerializerRegistry  given  the  type  name  of  the  format  returns  a  PrefsSerializer. 
Loading  preferences  is  as  simple  as: 

Prefs  prefs; 

fstream  inFile(“prefs.xml”); 

PrefsSerializer  &ps  = 

PrefsSerializer::instance().getPrefsSerializer(  “XML” ); 
try{ 

ps.load(  prefs,  inFile ); 

} 

catch  (Exception  e) 

{...} 

Saving  is  almost  exactly  the  same  except  the  call  to  PrefsSerializer  would  be 
save()  instead  of  load(). 


Structure 

An  overview  of  the  design  that  implements  the  preference  system  is  shown  in  the 
UML  diagram  in  Figure  1 . 
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Figure  1 :  Preference  Pattern  Structure  Overview 
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The  preference  system  contains  a  core  set  of  classes  that  control  the  storage 
and  conversion  of  preferences  as  shown  in  Figure  2  below^  _ 


Figure  2:  Preference  Pattern  Basic  Structure 
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The  Prefs  class  can  generate  a  group/variable  tree  from  the  stored  preferences. 
Subclasses  of  the  PrefsSerializer  interface  can  use  the  group/variable  tree  to 
serialize  the  Prefs  class  into  any  user  defined  format  as  shown  in  Figure  3  below. 
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Figure  3:  Preference  Pattern  Serialization 
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The  PrefsEditor  allows  the  user  of  the  application  to  graphically  edit  the  Prefs 
class.  The  PrefsEditor  is  displayed  in  a  PrefsDialog  as  shown  in  Figure  4: 
Preference  Editor  Pattern.  The  editor  also  uses  the  group/variable  tree  to  build 
and  layout  the  editor  components.  The  Converters  provide  the  individual  editor 
components. 
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Figure  4:  Preference  Editor  Pattern 
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Participant  Descriptions 

The  following  participants  provide  the  interface  or  API  to  the  users  of  the  library. 

Prefs 

•  Provides  an  interface  to  users  of  the  preference  system  to  store  and 
retrieve  all  preferences. 

•  Central  storage  for  the  Property  class. 

•  Categorizes  each  Property  by  using  a  variable  name  and  group  name. 

•  Provides  a  group  name  stack  for  setting  and  getting  variables. 

•  Returns  a  tree  using  GroupElements  and  VarElements  to  browse  the  Prefs 
structure. 

PrefsSerlalizer 

•  Interface  for  loading  and  saving  a  Prefs  class. 

•  This  class  should  be  subclassed  to  support  a  particular  format. 

•  The  subclasses  of  PrefsSerializer  must  ensure  groups,  variables  and 
values  are  saved  and  reloaded  correctly. 

PrefsSerializerRegistry 

•  Registers  an  implementation  of  PrefsSerializer. 

•  The  PrefsSerializerRegistry  is  associated  with  a  name  defined  by  each 
PrefsSerializer. 

PrefsDialog  and  PrefsEditor 

•  PrefsEditor  provides  a  browsing  and  editing  capability  for  the  preferences. 

•  PrefsDialog  displays  the  PrefsEditor  in  a  window.  PrefsDialog  handles  apply 
and  cancel  cases. 

•  Both  the  PrefsEditor  and  the  PrefsDialog  will  require  integration  into  the 
target  platform  toolkit. 

The  following  participants  provide  internal  functionality  for  the  preference  system. 

Property 

•  Stores  a  single  preference  data  item  along  with  type  information  about  that 
data  item. 

•  Provides  a  convenience  method  to  return  a  Converter  for  the  Property  type. 

Converter 

•  Interface  for  converting  a  Property  between  the  mediums:  GUI,  text,  and 
binary. 
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•  There  must  be  an  implementation  of  Converter  for  every  type  that  the 
preference  system  needs  to  handle. 

ConverterWIdget 

•  A  GUI  component  allows  the  user  to  edit  a  specific  Property  type. 

•  There  must  be  an  implementation  of  ConverterWidget  for  every 
implementation  of  Converter. 

ConverterRegistry 

•  Associates  the  Converter  with  a  particular  data  type. 


GroupElement  and  VarElement 

•  Used  to  access  the  tree  categorization  of  group  and  variable  names 
defined  by  the  Prefs  class.  The  GroupElement  class  stores  a  group  name. 
The  VarElement  class  stores  a  variable  name. 

•  Useful  for  operations  such  as  creation  of  a  GUI  and  serialization. 

•  The  GroupElement  and  VarElement  do  not  actually  contain  any  preference 
values;  they  contain  the  group  names  and  variable  names. 

Participant  Coliaborations 

This  section  describes  on  a  conceptual  level  how  the  participants  work  together. 
Section  3:  C++  Implementation  of  Preference  Pattern  discusses  several 
implementation  issues  involved  in  the  actual  implementation  of  several  of  these 
classes. 

Prefs 

•  set(),  get(),  getPropertyO 

o  Uses  Property  to  store  and  retrieve  the  values. 

•  getGroupElementTreeO 

o  Creates  the  GroupElement  and  VarElements. 

0  Returns  parent  GroupElement. 

•  pushGroupO,  popGroupO,  getGroupO 

0  Group  stack  accessor  methods  are  provided  as  convenience  instead  of 
passing  the  group  information  to  every  set()  and  get()  method  call. 

0  These  methods  allow  the  group  name  to  be  hidden  from  the  code 
where  individual  variables  are  set.  This  allows  for  greater  flexibility  and 
maintainability  of  group  categorization. 

GroupElement  and  VarElement 
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•  Uses  a  tree  structure  where  the  first  GroupElement  is  the  parent  node  and 
the  VarElements  are  the  children  nodes. 

•  A  GroupElement  can  contain  another  GroupElement  and  VarElement  as 
children. 

ConverterRegistry 

•  Uses  the  type  information  method  defined  by  the  Converter  interface  to 
register  the  Converter. 

•  When  a  Converter  is  needed  for  a  Property,  it  can  be  requested  from  the 
ConverterRegistry  by  matching  the  registered  type  information  with  the 
Property  type  information. 

Subclasses  of  Converter 

•  Converts  between  a  medium  and  the  corresponding  Property  type.  The 
mediums  currently  defined  for  conversion  are  text,  binary,  and 
ConverterWidget. 

•  Uses  the  corresponding  ConverterWidget  to  convert  between  the  GUI. 
Property 

•  getConverterQ 

0  Passes  its  own  type  information  to  the  ConverterRegistry  which  returns 
a  Converter  for  the  Property. 


PrefsEditor 

•  The  editor  uses  a  layout  scheme  that  allows  the  user  to  browse  the  group 
and  variables.  The  editor  also  must  allow  the  user  to  edit  the  values  for 
the  variables. 

•  The  browser  is  built  by  using  the  structure  provided  by  using  the 
GroupElement  and  VarElement  classes.  The  GroupElement  is  retrieved  by 
calling  the  Prefs  method  getElementGroupTree().  The  model  tree  provides 
the  group  organizations  and  the  variable  names  to  layout  the  editor. 

•  The  ConverterWidget  must  be  retrieved  for  the  variable  to  actually  edit  the 
object.  Once  the  editor  widget  is  retrieved,  it  must  be  added  to  the  layout 
of  the  PrefsEditor. 

0  To  retrieve  the  ConverterWidget,  the  variable  name  must  be  passed  to 
the  Prefs  class.  The  variable  names  will  be  known  from  the  model  tree. 
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The  Prefs  class  returns  a  Property  which  provides  the  corresponding 
ConverterWidget.  The  actual  method  calls  will  be  similar  to: 


//  get  the  property  given  the  variable  and  group  name 
Property  &prop  =  prefs.getProperty(varName,  groupName); 

//  get  the  converter  widget  from  the  property  and  show  it 
ConverterWidget  widget  =  prop.getConverter().toGUI(); 

add  WidgetT oLayout(widget) ; 

0  After  the  ConverterWidget  has  been  modified,  the  value  needs  to  be 
extracted  out  of  the  ConverterWidget  and  stored  back  into  the  Prefs 
class.  The  method  calls  to  perform  that  action  should  be  similar  to: 

//  get  the  property  back  out  of  the  widget 

Property  &prop  =  property.getConverter().fromGUI(  widget ); 

//  store  the  modified  property  into  the  Prefs  object 
prefs.set(varName,  prop,  groupName); 

o  The  editor  will  need  to  be  rebuilt  or  relayed  out  whenever  the  setPrefs() 
method  is  called. 

PrefsDialog 

•  Composed  of  a  PrefsEditor. 

•  If  apply  is  clicked,  the  Prefs  object  used  in  the  PrefsEditor  is  copied  to  the 
Prefs  object  passed  to  the  dialog. 

o  If  cancel  is  clicked,  no  reassignments  are  done  to  the  original  Prefs 
object  passed  to  the  dialog. 

Subclasses  of  PrefsSerializer 

•  The  save()  method  uses  the  model  provided  by  Prefs 
getGroupElementTreeO  to  traverse  through  all  preference  elements. 

•  For  every  VarElement,  saves  the  GroupElement  full  group  name.  For  each 
VarElement  It  saves  the  variable  name  and  corresponding  Property  value. 

•  Individual  preference  values  can  be  saved  to  text  files  using 
property.getConveter().toAscii()  methods.  Binary  files  can  use  the  toBinaryO 
methods. 
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•  The  load()  method  should  read  and  tokenize  each  line. 

0  Each  line  should  contain  the  variable  name,  group,  description  and 
value. 

o  These  values  should  be  passed  to  the  Prefs  class  set()  method. 

PrefsSerlallzerRegistry 

•  The  library  user  must  register  a  subclass  of  PrefsSerializer  and  associate 
with  a  meaningful  name 

Consequences 

The  preference  pattern  has  the  following  consequences 

1 .  Guarantees  data  will  be  type  safely  stored  and  retrieved. 

2.  Property  class  and  the  implementations  of  Converter  decouple  the  original 
data  item  from  how  to  edit  and  save  the  object. 

3.  Conversion  algorithms  between  strings,  binary,  and  GUI  can  be  changed 
easily  without  other  operations  such  as  saving  and  loading  being  aware. 

4.  By  using  multiple  ConverterRegistry  objects,  multiple  conversion  schemes 
can  be  used.  For  example,  a  SQL  ConverterRegistry  can  be  used  to 
convert  information  from  a  database.  A  different  ConverterRegistry  can  be 
used  to  convert  the  same  data  type  from  a  user  specified  format. 

5.  Every  type  that  needs  to  be  converted  (i.e.  any  type  that  is  a  preference) 
must  have  a  Converter  defined  for  it.  This  could  lead  to  cases  where  the 
developer  creates  a  Prefs  object,  storing  a  type  that  the  Converter  cannot 
handle,  preventing  the  user  from  entering  that  information  and  saving  or 
loading  that  Property. 

Pattern  Remarks 

The  preference  pattern  itself  is  actually  a  composite  of  relatively 
straightforward  predefined  patterns^.  The  GroupElement  and  VarElement  is 
actually  just  a  variation  of  the  Composite  pattern.  The  Property  and  Converter  is  a 
variation  of  the  Bridge  pattern.  The  ConverterRegistry  and  the 
PrefsSerializerRegistry  is  a  Builder  pattern. 


^  See  Design  Patterns:  Elements  of  Object-Oriented  Software  for  further  definitions  of  the  referred  patterns. 
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Section  3:  C++  Implementation  of  Preference  Pattern 


The  implementation  of  the  preference  pattern  has  some  difficult  issues  to 
overcome.  This  section  will  outline  many  of  the  issues  involved. 

The  core  and  perhaps  hardest  decision  in  implementing  the  preference 
pattern  involves  determining  the  type  of  an  object  at  run  time  and  general  object 
anonymity.  The  other  issues  discussed  in  this  section  are:  using  the 
group/variable  tree,  creating  a  generic  editor,  deciding  between  multiple 
ConverterRegistry  objects  or  a  using  singleton  pattern,  storing  all  necessary 
information  for  loading  and  saving,  and  defining  all  valid  Converter  types. 

In  the  following  list  of  possible  C++  solutions  to  these  problems  are 
provided.  A  guide  to  help  the  developer  choose  among  the  proposed  solutions  is 
also  provided  when  appropriate. 

Determining  the  Type  of  an  Object  at  Run  Time 

Issues 

1 .  Matching  the  appropriate  Converter  to  a  Property 

2.  Type  checking  when  storing  or  retrieving  a  value  with  a  Property. 

Solutions 

Two  possible  approaches  of  determining  the  type  of  an  object  at  run  time 
are  to  use  compiler  supported  run  time  type  identification  or  using  inheritance. 

Run  Time  Type  Identification 

The  Converter  and  Property  classes  can  be  implemented  by  utilizing 
compiler  supported  run  time  type  identification  (RTTI)''.  The  primary 
implementation  issues  are  listed  below®. 

1 .  The  Property  class’s  set()  method  should  copy  the  typejnfo  class  and  the 
value  of  the  variable.  The  next  subheading  Using  Object  Anonymity 
discusses  possible  solutions  to  storing  and  retrieving  the  value  of  the 
variable. 


*  The  C++  standard  defines  a  method  typeid  ( <var  iable> )  that  returns  a  type_inf  o  class.  The 
type_info  class  has  a  method  that  will  return  the  name  (const  char  *)  of  the  type. 

^  Please  see  Appendix  B  for  the  full  implementation  of  the  Property  and  Converter  classes. 
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2.  The  Property  class’s  get(  &<dest  var>)  method  should  take  the  destination 
variable  in  which  to  store  the  Property’s  value.  Then  a  type  comparison 
can  be  performed  between  the  destination  variable  and  the  stored 
typejnfo  class.  An  exception  can  be  thrown  if  the  type  match  fails. 

3.  A  Converter  for  each  valid  Property  type  should  be  registered  to  the 
ConverterRegistry.  The  ConverterRegistry  would  associate  the  name 
returned  by  the  Converter’s  typejnfo  with  the  Converter  class.  After  a 
Converter  is  registered,  a  Property  can  pass  the  its  typejnfo  to  the 
ConverterRegistry  and  the  Property’s  associated  Converter  will  be  returned. 

Benefits 

The  RTTI  approach  involves  only  a  few  lines  of  code  and  should  have  no 
impact  on  the  design  of  the  rest  of  the  application. 

Liabilities 

The  downside  to  this  approach  is  the  dependence  that  compiler  will  follow 
the  C++  standards  and  implement  RTTI.  However,  our  organization  is  doing 
cross  platform  development  using  three  different  compilers  and  found  RTTI  to  be 
implemented  by  all  compilers. 

Inheritance 

Another  option  is  to  use  inheritance  to  provide  type  information. 
Inheritance  from  the  Property  class  must  be  used  to  provide  an  implementation 
for  each  preference  type.  The  primary  implementation  steps  are  listed  below. 

1 .  Property  base  class  is  actually  an  interface  that  defines  the  set(),  get()and  a 
getTypeNameO  methods.  These  methods  must  be  implemented  in  each 
subclass  of  Property. 

2.  Converter  getTypeNameO  methods  return  value  are  matched  against  the 
Property  getTypeNameO  method.  The  Property  and  Converter 
getTypeNameO  methods  are  used  to  match  subclasses  of  Converter  up 
with  subclasses  of  Property. 

Benefits 

This  solution  guarantees  compiler  independence  and  provides  a 
mechanism  for  object  reflection  similar  to  Java’s. 

Liabilities 

The  inheritance  solution  will  have  a  large  impact  on  the  design  of  the  Prefs 
system  and  possibly  an  application;  i.e.  possible  force  future  use  of  multiple 
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inheritance.  Also,  there  would  be  an  extremely  large  overhead  for  having  to  write 
a  Property  class  for  every  type. 

The  user  would  have  to  instantiate  the  appropriate  Property  upon  creation 
of  a  class  instead  of  being  able  to  call  a  set  method  to  an  already  existing 
Property  object. 

There  would  be  no  ability  to  perform  Property  assignments  since  each 
Property  may  be  of  a  different  type.  For  instance,  you  could  not  assign  a 
DoubleProperty  to  a  IntProperty  without  writing  overloaded  equal  operators 
between  every  type. 

Using  Object  Anonymity  in  Property  Implementation 

Issues 

1.  Storing  any  preference  data  object  inside  of  the  Property  class. 

2.  Passing  any  preference  data  type  to  Property’s  set()  method. 

3.  Retrieving  the  preference  data  back  out  of  the  Property  class. 

4.  Deep  copy  versus  shallow  copy  when  assigning  an  object  to  the  Property 
class. 

Solutions 

Two  approaches  are  presented  to  solve  the  object  anonymity  problem. 

One  is  to  use  templated  member  functions  and  a  templated  storage  class.  The 
other  is  to  use  the  same  inheritance  solution  described  in  the  subsection 
Determining  the  Type  of  an  Object  at  Run  Time. 

Either  solution  will  eventually  involve  the  Property  class  storing  a  data 
object.  The  third  subsection  describes  the  benefits  an  liabilities  of  performing  a 
deep  or  shallow  copy  of  the  data  object. 

Templated  Member  Functions  and  Templated  Storage  Class 

The  Property  class’s  set()  and  get()  methods  can  be  implemented  using 
templated  member  functions  to  pass  and  return  the  values  in  and  out  of  the 
class. 

Templated  member  functions  allow  the  methods  to  be  templated  while  the 
class  itself  does  not  have  to  be  templated.  A  non-templated  class  is  important 
since  later  when  referring  the  class  during  operations  such  as  saving  or 


17 


converting  to  the  GUI,  each  Property’s  type  is  unknown;  i.e.  the  type  to  reference 
the  Property  will  be  unknown. 

Templated  member  functions  allow  data  to  be  generically  passed  into  the 
Property  class,  however  the  issue  of  how  to  store  this  templated  data  as  a 
attribute  of  the  Property  class  needs  to  be  resolved.  The  two  approaches  to 
storing  the  templated  data  is  described  below. 

1 .  The  simple  but  flawed  approach  is  to  store  the  data  using  a  void  pointer  by 
doing  an  assignment  such  as: 

fData  =  static_cast<void  *>(copiedTemplatedParam); 

The  problem  with  this  approach  is  in  the  destruction  of  the  data.  Since  the 
data  is  being  stored  as  a  void  pointer,  the  compiler  does  not  know  what 
type  the  value  is  and  is  unable  to  properly  call  the  destructor  of  the  type 
and  free  the  memory.  The  memory  leak  problem  will  only  occur  if  the 
Property  class  is  doing  a  deep  copy  (recommended)  instead  of  a  shallow 
copy. 

2.  A  slightly  more  complex  solution  but  one  that  does  not  leak  memory  is  to 
create  a  base  class  called  DataHolder,  which  provides  an  interface  to 
retrieve  the  data  from  the  internal  class.  The  DataHolder  can  be 
subclassed  to  a  TypedDataHolder.  The  TypedDataHolder  is  actually  a 
templated  class  and  stores  the  data  using  the  templated  type  as  the  data 
as  shown  from  the  code  excerpt  from  Appendix  A. 03  -  Property.h  below: 

class  DataHolder 
{ 

public: 

virtual  ~DataHolder()  { } 

virtual  void  get(void  *data,  const  std::typeJnfo&  tinfo)  const=0; 

virtual  const  std::typeJnfo  &typelnfo()const=0; 
virtual  DataHolder  *cIone()  const=0; 

}; 


template  <class  type> 
class  TypedDataHolder :  public  DataHolder 
{ 

public : 

TypedDataHolder(const  type  data,  const  std::typeJnfo&  tinfo) : 
fData(data).  fTypelnfo(tinfo) 

{ 

if  (typeid(fData)  !=  tinfo) 
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} 


throw  PropertyTypeMismatchException("TypedDataHolder(data,  info)",  fTypelnfo.name(), 

tinfo.nameO); 


-TypedDataHolderO 

{) 

void  get(void  ‘data,  const  std::typeJnfo&  tinfo)  const 
{ 

if  (tinfo  !=  fTypeInfo) 

throw  PropertyTypeMismatchExcopfionC'get",  fTypelnfo.name(),  tinfo.nameO); 


type  ‘typedParam  =  (type  *)data: 
‘typedParam  =  fData; 

} 


const  std::typeJnfo  &typelnfo()  const  { return  fTypeInfo; } 

DataHolder  *clone()  const 
{ 

return  new  TypedDataHolder<type>(fData,  fTypeInfo); 
} 


private : 
type  fData; 

const  std;:type_info&  fTypeInfo; 


Examples 

We  defined  the  Property  get()  method  to  take  both  the  destination  variable 
and  the  typejnfo  as  parameters.  This  forces  the  caller  of  the  Property  object  to 
explicitly  specify  what  type  of  object  they  think  they  should  be  retrieving  which 
adds  to  code  readability  and  maintainability. 

The  following  example  shows  how  to  use  the  preference  library  to  store 
and  retrieve  information  in  and  out  of  a  Prefs  object.  Internally,  these  methods 
will  use  a  Property  object  to  store  or  retrieve  the  information. 

Prefs  prefs; 

prefs.set(“maxWidth”,  1000,  type_id(int),  “Windows”,  “Maximum  width  of  a 

window”); 

prefs.setC'userName”,  QStringD,  typeJd(QString),  “Personal”,  “User  name”); 

int  width; 

QString  userName; 
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prefs.get(“maxWidth”,  width,  type_id(int),  “Windows”); 
prefs.get(“userName”,  userName,  typeJd(QString),  “Personal"); 

Inheritance 

The  Property  class  can  also  be  implemented  by  using  inheritance  as 
described  in  the  subsection  above:  Determining  the  Type  of  an  Object  at  Run 
Time.  The  same  benefits  and  liabilities  for  RTTI  versus  inheritance  described  in 
Determining  the  Type  of  an  Object  at  Run  Time  applies  for  Object  Anonymity  as 
well. 

Deep  or  Shallow  Copy 

The  second  issue  to  be  determined  with  either  solution  is  whether  a  deep 
copy  or  shallow  copy  is  done  in  the  set()  method. 

A  deep  copy  is  much  safer  by  guaranteeing  no  dangling  pointer  and 
ensures  data  encapsulation.  A  deep  copy  however  requires  that  every  class  that 
needs  to  be  stored  into  the  Property  have  an  overloaded  equals  operator  or  copy 
constructor  defined  for  that  type.  This  shouldn’t  be  a  problem  since  all 
preference  types  should  be  a  relatively  basic  type  and  be  easily  and  obviously 
assignable. 

A  shallow  copy  could  allow  for  the  possibility  of  dangling  pointers  and 
breaks  encapsulation  since  a  external  code  could  modify  the  pointer.  A  shallow 
copy  would  have  a  faster  performance  since  a  copy  would  not  need  to  be  done 
during  preference  assignment  and  retrieval.  Regardless,  breaking  encapsulation 
is  a  major  object  oriented  mistake  and  should  be  avoided. 

Using  the  GroupA/ariable  Tree 

Issues 

1 .  Browsing  and  iterating  through  the  structure  of  the  preferences. 

2.  Implementation  of  PrefsSerializer. 

3.  Implementation  of  PrefsEditor. 

Solutions 

Browsing  and  Iterating 

The  group/variable  tree  is  represented  by  two  classes,  GroupElement  and 
VarElement. 
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The  GroupElement  objects  are  the  parent  nodes  while  the  VarElement 
objects  are  the  children  nodes.  GroupElement  satisfies  the  composite  pattern  by 
being  composed  of  itself  as  well  as  the  VarElement.  At  each  level,  group  and 
variable  names  are  guaranteed  to  be  unique;  i.e.  two  groups  cannot  have  the 
same  name  and  two  variables  cannot  have  the  same  name. 

The  group/variable  tree  only  contains  group  names  and  variable  names 
and  does  not  contain  the  values  of  individual  preferences.  To  retrieve  values  of 
individual  preferences,  the  Prefs  get()  method  must  be  called,  passing  the 
variable  and  group  information  provided  by  the  model. 

Iterating  through  the  model  should  look  similar  to  the  following  code.  The 
example  code  outputs  the  group  and  variable  tree  plus  the  value  of  each 
preference. 

Prefs  prefs; 

//  preferences  have  already  been  stored 

GroupElement  ‘parent  =  prefs.getGroupElementTree(); 

recursiveOutput(prefs,  parent): 

void  recursiveOutput(Prefs  &prefs,  GroupElement  ‘node) 

{ 

//  output  variable  names  for  the  group 
for  (QListlterator<VarElement>  entrylter  = 
node->getVarEntrylterator() ; 
entrylter.current(): 

++entrylter) 

outputVarElement(prefs,  ‘entrylter.currentO,  ‘node); 

//  recursively  iterate  through  the  tree 
for  (QListlterator<GroupElement>  childreniter  = 
node->getSubgrouplterator(): 
childrenIter.currentO: 

++childrenlter) 

recursiveOutputfprefs,  childrenIter.currentO; 

} 

void  outputVarElement(Prefs  &prefs, 

const  VarElement  &entry, 
const  GroupElement  &group) 
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{ 

cout «  group.getFullGroupNameO; 
cout « “>“ «  entry. getNameQ; 

const  Property  &prop  =  prefs.getProperty(entry.getName(), 

group.getFullGroupNameO); 
cout « “  =  “ «  prop.getConverter().toAscii(  prop ); 

} 

Serializer  and  Editor 

A  similar  approach  to  the  above  example  could  be  used  in  the 
implementation  of  the  PrefsEditor  or  in  subclasses  of  PrefsSerializer. 

The  saving  algorithm  would  replace  the  functionoutputVarElement()  with  a 
function  called  saveElementQ.  The  preference  information  can  either  be  saved  to 
a  text  or  binary  file.  The  use  of  the  text  conversion  methods  (toAscii(),  fromAsciiO) 
versus  the  binary  conversion  methods  (toBinaryQ,  fromBinaryQ)  depends  on 
whether  the  file  format  is  text  or  binary. 

As  discussed  in  the  Participant  Description  and  Participant  Collaboration 
subsections  in  Section  2,  the  PrefsEditor  allows  the  user  to  browse  and  edit  the 
preferences.  The  algorithm  required  to  group  and  layout  the  browsing  and 
editing  components  will  need  to  iterate  through  the  group  and  variables  similar  to 
the  example  above.  The  points  below  suggest  possible  alterations  to  the 
example  in  the  building  of  the  PrefsEditor  layout: 

•  Instead  of  just  iterating  through  the  groups  and  variables,  a  tree  GUI 
component  node  would  be  created  and  inserted  with  the  group  or 
variable  name. 

•  The  variable  nodes  (VarElement)  could  either  be  children  of  the  group 
tree  or  could  be  a  separated  list  displayed  when  a  group  is  selected. 

Creating  a  Standard  Editor 

Issues 

1.  Integrating  the  ConverterWidget,  PrefsEditor,  and  PrefsDialog  with  the  target 
platform  or  toolkit. 

2.  Organizing  the  PrefsEditor  to  provide  the  user  with  straightforward  editing 
of  the  preferences. 

3.  Performing  validity  checking  on  data  from  the  user. 
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Solutions 

Please  read  the  Participant  Descriptions  in  Section  2  for  a  description  of 
the  PrefsEditor  and  PrefsDialog.  This  section’s  subsection  Using  the 
Group/Variable  tree  describes  how  to  use  the  group/variable  tree  to  get  the 
necessary  information  for  building  the  editor. 

Editor  Layout 

The  editor  needs  to  present  the  user  with  the  variable  names,  variable 
descriptions,  ability  to  edit  the  values  and  some  intelligent  organization.  Two 
possible  approaches  are  to  use  a  modified  tree  browser  to  edit  one  preference  at 
time  or  to  use  a  group  pane  dialog. 

The  modified  tree  browser  creates  an  editor  split  into  two  panes.  The  left 
pane  could  be  a  tree  browser  as  described  in  Using  the  GroupA/ariable  tree. 

The  right  pane  could  be  the  editor  for  the  selected  variable  in  the  tree.  The  right 
pane  might  also  display  the  description  for  the  editing  variable.  An  example  of 
this  organization  is  shown  below. 
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Figure  5:  Split  Pane  Prefs  Editor 


Another  approach  is  to  use  a  tab  dialog  for  the  group  names.  Inside  each 
tab  would  be  a  vertical  list  containing  a  line  that  contains  the  variable  name,  the 
variable  descriptions  and  the  editor  widget  for  that  variable. 

GUI  Integration 

Any  graphical  component  described  in  the  pattern  needs  to  be  integrated 
into  the  target  platform  or  GUI  toolkit.  The  classes  involved  in  integrate  with  the 
target  windowing  environment  are  PrefsEditor,  PrefsDialog  and  ConverterWidget. 

The  PrefsEditor  and  ConverterWidget  should  inherit  from  the  common 
graphical  widget  such  as  QWidget  for  Qt  or  JComponent  for  Java  1 .2.  The 
PrefsDialog  should  inherit  from  a  window  or  dialog  component  such  as  QDialog 
for  Qt.  The  subclasses  of  ConverterWidget  should  probably  be  composed  of  basic 
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graphical  editing  components  such  as  QStringConverter  being  composed  of 
QMultiLineEdit  widget  for  Qt. 

Validity  Checking 

Each  implementation  of  each  ConverterWidget’s  getValue().method  should 
perform  some  validity  checking  on  the  data  received  from  the  user.  Before 
storing  the  value  from  the  input  component  into  a  Property,  the  value  should 
validated  to  be  of  the  correct  type.  For  example,  a  double  value  could  not  be 
stored  into  an  integer  Property.  Ideally,  the  ConverterWidget  should  be 
implemented  so  only  the  valid  information  for  that  type  could  be  entered  by  the 
user. 

Multiple  ConverterRegistry  Instances  or  Singleton 

Issues 

1 .  Should  multiple  conversion  formats  for  Property  objects  be  allowed  within  one 
application. 

Solutions 

It  is  helpful  to  recognize  whether  multiple  conversion  formats  will  be  used 
within  one  application  or  whether  it  is  virtually  guaranteed  to  use  only  one 
conversion  algorithm.  For  example,  there  may  be  an  application  where  Property 
object  will  be  saved  to  both  an  SQL  database,  which  has  one  conversion  format 
style,  and  a  set  of  Property  objects  that  will  be  saved  to  a  XML  preference  file.  If 
it  is  not  clear  that  only  a  single  registry  will  be  used,  it  is  a  good  design  decision 
to  plan  on  using  multiple  ConverterRegistry  objects. 

•  If  multiple  conversions  are  required,  then  the  ConverterRegistry  should 
be  passed  through  to  the  Property  when  Property.getConverterQ  is 
called. 

•  If  multiple  conversions  are  not  required,  then  Property.getConverter() 
can  return  the  appropriate  Converter  by  using  the 
ConverterRegistry.instanceQ  singleton  method. 
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Saving  and  Loading  file  format 

Issues 

1 .  Format  must  support  storing  group  information. 

2.  Format  must  support  storing  type  information  that  is  valid-across 
compilers. 

3.  Binary  versus  text  formats. 

Solutions 

There  are  no  hard  and  fast  solutions  to  the  issues  listed  above,  but  they 
should  be  kept  in  mind  when  creating  a  file  format. 

Whatever  the  file  format  that  is  chosen,  make  sure  it  does  not  limit  the 
naming  of  a  group  or  variable  name.  For  example,  the  file  format  probably  should 
not  delimit  on  spaces  or  quotes  since  both  will  probably  be  used  inside  variable 
or  group  names.  Possible  solutions  to  choosing  an  serialization  implementation 
are  listed  below. 

•  One  possible  solution  is  to  create  a  simple  text  preference  file  format  as 
we  did  in  our  solution. 

•  Another  more  flexible  solution  may  be  to  use  XML  to  define  the  preference 
file  format. 

•  Saving  in  a  binary  file  is  also  a  possibility;  however  saving  in  a  text  file  still 
allows  the  user  to  be  able  to  edit  the  file  manually.  This  maybe 
considered  a  benefit  or  liability  depending  on  your  situation. 

One  possible  source  of  complications  may  come  about  in  storing  the  type 
information.  If  Property  is  implemented  using  RTTI,  the  type  name  string  should 
not  be  used  since  the  string  returned  is  not  the  same  across  platforms  or  even 
the  same  across  compilers. 

A  solution  is  to  create  a  method  in  the  Converter  called  getTypeNamef) 
which  must  be  implemented  in  the  subclass  of  each  Converter.  This  guarantees 
that  the  type  name  will  be  valid  across  compilers  and  across  platforms.  This  API 
is  shown  in  the  structure  diagrams  of  the  pattern. 
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Documenting  All  Valid  Types 

Issues 

1 .  Documenting  a  rule  for  valid  preference  types. 

2.  Creating  a  the  appropriate  subclasses  for  all  valid  types. ' 

Solutions 

Rules  for  Valid  Preference  Types 

It  is  a  good  idea  to  define  a  set  of  valid  preference  types  to  provide 
discipline  to  the  users  of  the  preference  system.  For  example  a  class  that 
contains  lists,  strings  and  booleans  probably  is  too  complex  to  be  considered  a 
preference  type.  Here  are  possible  standards  that  implementers  of  the 
preference  system  may  want  to  adopt. 

•  Support  only  built  in  types  (such  as  int,  float,  double,  etc.).  This  solution  will 
require  the  smallest  amount  of  coding  in  the  implementation  of  the 
Converter  classes.  However  this  is  probably  not  sufficient  for  most 
applications. 

•  Support  built  in  types  plus  a  small-defined  set  of  simple  classes  such  as 
Color ,  Date,  and  String. 

•  Support  the  types  above  plus  a  list  of  the  type  basic  types. 

Creating  Subclasses  for  All  Valid  Types 

If  using  RTTI,  a  subclass  for  Converter  and  ConverterWidget  should  be 
defined  for  each  valid  preference  type.  If  not  using  RTTI,  then  a  subclass  for 
Property  must  also  exist  for  each  valid  preference  type. 
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Section  4:  Conclusion 


The  preference  pattern  and  C++  implementation  solves  the  common 
requirement  to  provide  a  user  interface  and  serialization  ability  for  a  generic  set 
of  preferences.  This  report  outlined  the  preference  pattern’s  applicability, 
usability,  structure,  participants  and  participant  collaboration.  The  C++ 
implementation  section  described  the  key  implementation  issues  of  the  pattern 
and  some  possible  solution  to  those  issues. 

The  preference  system  provides  a  method  of  being  able  to  convert  a  set  of 
generic  properties  to  multiple  mediums.  For  these  set  of  requirements,  the 
mediums  were  converting  between  a  GUI  and  converting  between  a  file.  This 
same  property  conversion  pattern  may  be  extended  for  future  projects  where 
new  conversion  mediums  may  be  added. 
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Appendix  A  -  Sample  C++  Code 

o  There  is  too  much  code  to  provide  for  a  complete  code  listing  in  this  report. 
The  entire  library  can  be  requested  by  contacting  the  Naval  Research  Library 
in  Washington  DC.  Please  email  all  requests  to  stern@enews.nrl.navv.mil. 
o  The  code  listing  given  below  provides  the  most  difficult  parts  of  the 
implementation  including  the  Property  class,  the  Converter  interface,  some 
sample  converters  and  the  SimplePrefsSerializer.  Note  that  the  implementation 
uses  Qt’s  foundation  libraries  for  data  structures  and  graphical  items.  A  non¬ 
commercial  use  of  Qt  can  be  downloaded  for  free  at  www.troll.no. 
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Appendix  A.01  -  Prefs.h 

#ifndefCPL_PREFS_H 
#define  CPL_PREFS_H 
#inclucle  <qstring.h> 

#include  <qlist.h> 

#include  <qstring!ist.h> 

#include  <qdict.h> 

#include  "CPUConvert/Property.h" 

#include  “CPL/Prefs/GroupElement.h" 

#include  "PrefsException.h" 

/******************************************************************♦********* 

***** 

Classification:  UNCLASSIFIED 

Classified  By:  ***** 

Declassify  On:  ***** 

***** 

**************************************************************************** 


/ 

***** 


*  Developed  by:  Naval  Reseapp  Laboratory,  Tactical  Electronic  Warfare  Div. 

*  Effectiveness  of  Navy  Electronic  Warfare  Systems,  Code  5707 

*  4555  Overlook  Ave. 

*  Washington,  D.C.  20375-5339 

* 

*  For  more  information  please  call  202-767-2897  or  send  email  to 

*  enews@enews.nrl.navy.mjl 

*  The  U.S.  Government  retains  all  rights  to  use,  duplicate,  distribute, 

*  disclose,  or  release  this  software. 

V 

/**  class  Prefs 

* 

*  Base  class  for  all  configuration  storage  to  map  group 

*  (category)  names  to 

*  variable  names  and  values.  The  keys  may  be  case  sensitive. 

* 

*  Each  set  function  can  take  an  optional  group.  If  group 

*  string  is  not  given,  then  the  classes’s  current  group  string 

*  (set  by  set  method,  or  push  calls)  \will  be  used. 

* 

*  Each  get  method  will  throw 
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*  Stores  type  information  for  each  variable  to  allow  for  strict 

*  type  checking  when  saving  or  loading. 

*  The  group  string  is  separated  by  dots.  For  example: 

*  builder.graphics.gl.color  is  a  valid  group 
V 

class  Prefs 

{ 

friend  class  PrefsSerialization; 
public: 

r*@param  primeHashTableSize  the  number  of  buckets  (prime  number)  to  create  the 
*  collision  hash  table;  see  QDict  html  page  for  a  list  of  primes 
V 

Prefs(bool  keyCaseSensitive=false,  int  primeHashTableSize=521); 


/**@  return  true  if  the  group. varName  Is  found,  ie.  is  gettable  V 

bool  exlsts(const  QString  &varName,  QString  group=QStrlng::null)  const; 


template<class  type> 

bool  set(const  QString  &varName,  const  type&  value,  const  std::type_lnfo&  typeinfo, 
QString  group=QString::null,  QString  desc=QStrlng::nu!l) 

{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement*  aValuePtr  =  fEntryDict.flnd(key); 
if  (aValuePtr  ==  OL) 

{ 

try 

{ 

Property*  prop  =  new  Property(value,  typeinfo); 
aValuePtr  =  new  PrefsElement{varName,  prop,  desc); 
fEntryDict.insert(  key,  aValuePtr); 

} 

catch  (Exception  e) 

{ 

qDebug(''Prefs::set:  %s",  e.toString().ascll()); 
return  false; 

} 

} 

else 

{ 

try 

{ 

Property*  prop  =  new  Property(value,  typeinfo); 
aValuePtr->setProperty(prop); 
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} 

catch  (Exception  e) 

{ 

qDebug(“Prefs::set:  %s",  e.toString().ascii()): 
return  false; 

} 

} 

return  true; 

} 

bool  setProperty(const  QString  SvarName,  Property*  value, 

QString  group=QString::null,  QString  desc=QString:;null); 

/**  Sets  the  description  of  a  entry.  If  the  entry  exists,  the  desc  will  be  set  and 
*  true  will  be  returned.  If  the  entry  doesn't  exist,  false  will  be  returned 
*/ 

bool  setDesc(const  QString  &varName,  const  QString&  desc,  QString  group=QString::null); 
template<class  type> 

void  get(const  QString  &varName,  type&  outvalue,  const  std::typeJnfo&  typeinfo,  QString  group=QString::null) 

{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement  ‘aValuePtr  =  fEntryDict.find(  key ); 
if  (aValuePtr  ==  OL) 

throw  PretsEntryNotFoundException(  key ); 

Property*  prop  =  &aValuePtr->getProperty(); 
prop->get(outValue,  typeinfo); 

) 

template<class  type> 

void  get(const  QString  &varName,  type&  outvalue,  const  std;:typeJnfo&  typeinfo,  QString  group,  QStringS 
outDesc) 

{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement  *aValuePtr  =  fEntryDict.find(  key ); 
if  (aValueRr  ==  OL) 
throw  EntryNotFoundException(  key ); 

Property*  prop  =  &aValueRr->getProperty(); 
outDesc  =  aValueRr->getDesc(); 
prop->get(outValue,  typeinfo); 

) 

const  PropertyS  getProperty(const  QString  &varName,  QString  group=QString::null)  const; 
const  QString  getDesc(const  QString  &varName,  QString  group=QString::null)  const; 
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r*  pushes  another  layer  onto  the  group  stack  7 
void  pushGroup  (const  QString  &aGroup); 

/**  sets  the  current  group  string;  seperate  group/subgroup  categories  by  using  a  period;  such  as 
builder.graphics.colors  7 

void  setGroup  (const  QString  &formatedGroupString); 

/**@  return  the  popped  group  name7 
QString  popGroup  (); 

void  popAIIGroups  (); 

/**  the  current  group  stack  string  (,  delimited);  will  be  used  if  no  group  string  Is  provided  in  the  get/set  methods; 

uses  static  method  createGroupVarString( )  7 
QString  getCurrentGroup  ()  const; 

return  a  newed  GroupPrefs  that  provides  a  model  for  the  group  hierarchy;  user  must  delete  the  newed 
GroupPrefs7 

GroupElement  *getGroupElementTree()  const; 

bool  isKeyCaseSensitiveO  const  { return  fCaseSensitive; } 

/**@param  formatedGroupString  is  a  .  delimited  String,  containing  a  group  tree 

@param  lastTokenlsVar  true  (default)  if  the  last  token  in  the  formatedGroupString  is  a  variable  name,  not 

group 

@param  varName  return  parameter  to  store  the  var  name  if  lastTokenlsVar  is  true 
©return  a  string  list  of  group  names  and  var  name  Into  the  param  if  flagged  7 
static  QStringList  parseGroupVarString(const  QString  &formatedGroupString,  bool  lastTokenlsVar=true, 
QString  *varName=OL); 

/**©  return  a  single  string  using  the  .  delimiter  in  between  strings  7 
static  QString  createGroupVarString(const  QStringList  &strList); 

protected: 
class  PrefsElement 
{ 

friend  class  Prefs; 

friend  class  QDict<PrefsElement>; 

public: 

Property&  getPropertyO  const  { return  *fProperty; } 

QString  getDesc()  const  { return  fDesc; } 

QString  getName()  const  { return  fName; } 

void  setName(const  QString&  name)  { fName  =  name; } 

void  setDesc(const  QString&  desc)  { fDesc  =  desc; } 

void  setProperty(Property*  prop)  { delete(fProperty);  fProperty  =  prop; } 
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protected: 

PrefsElement(QString  name,  Property*  property,  QString  desc) 
:  fProperty(  property ),  fName(  name ),  fDesc(  desc )  {} 

-PrefsElementO  { delete  (fProperty); } 

private: 

Property*  fProperty; 

QString  fDesc; 

QString  fName; 

}; 


private: 

/**@shapeType  Dependency  Link 

*  ©label  creates*/ 

/*#  GroupPrefs  lnkUnnamed2*/ 

/**@shapeType  DependencyLink 

*  ©label  throws*/ 

/*#  PrefsEntryNotFoundException  InkUnnamedI*/ 
/**©shapeType  DependencyLink 

*  ©  label  throws*/ 

/*#  PropertylnvalidTypeExceptlon  InkUnnamedV 

QString  _getKey(QString  group,  const  QString  &varName)  const; 

/**  ©suppIierCardinality  0..* 

*  ©byValueV 

QDict<PrefsElement>  fEntryDict; 

QStringList  fCurrentGroup; 
bool  fCaseSensitive; 

}; 


#endlf//CPL_PREFS^H 


Appendix  A.02  -  Prefs.cpp 

#include  Trefs.h* 

#include  'CPL/Convert/Property.h“ 

#include  "CPL/Util/StringTokenizer.h“ 

Prefs::Prefs(bool  caseSensitive,  int  hashTableSize)  :fEntryDict(hashTableSize,  caseSensitive), 
fCaseSensitive(caseSensitive) 

{ 

fEntryDict.  setAutoDelete(true); 

} 

QString  Prefs::_getKey(QString  group,  const  QString  &varName)  const 

{ 
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if  (group.isNullO) 

group  =  getCurrentGroupO; 

QString  key  =  group; 
if  (Ikey.isEmptyO) 
key  += 

key  +=  varName; 

//  const  char  *asciiKey  =  key.ascll();  //  for  Inspection  in  cvd  DEBUG 
return  key; 

} 

bool  Prefs::setProperty(const  QString  &varName,  Property*  value, 

QString  group,  QString  desc) 

{ 

If  (value  ==  OL) 
return  false; 

QString  key  =  _getKey(group,  varName); 

PrefsElement*  aValuePtr  =  fEntryDict.find(key); 
if  (aValuePtr  ==  OL) 

{ 

aValuePtr  =  new  PrefsElement(varName,  value,  desc); 
fEntryDict.insert(  key,  aValuePtr); 

} 

else 

{ 

aValuePtr->setProperty(value); 

) 

return  true; 

} 

bool  Prefs::setDesc(const  QString  SvarName,  const  QString&  desc,  QString  group) 

{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement*  aValuePtr  =  fEntryDict.find(key); 
if  (aValuePtr  ==  OL) 

{ 

return  false; 

} 

else 

{ 

aValuePtr->setDesc(desc); 

} 

return  true; 

} 

const  Property&  Prefs::getProperty(const  QString  SvarName,  QString  group)  const 
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{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement  ‘aValuePtr  =  fEntryDlct.find{  key ); 
if  (aValueRr==:  OL) 

throw  PrefsEntryNotFoundException(  key ); 

return  aValueRr->getProperty(); 

} 

const  QString  Prefs::getDesc(const  QString  &varName,  QString  group)  const 

{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement  *aValuePtr  =  fEntryDict.find(  key ); 
if  (aValueRr  ==  OL) 

throw  PrefsEntryNotFoundException(  key ); 

return  aValueRr->getDesc(); 

} 

void  Prefs::pushGroup(const  QString  &aGroup) 

{ 

fCurrentGroup  +=  aGroup; 

} 

void  Prefs::setGroup(const  QString  &formatedGroupString) 

{ 

StringTokenizer  t(formatedGroupString, ".”); 
fCurrentGroup  =  t.toStringList(); 

} 

QString  Prefs::popGroup() 

{ 

QString  lastGroup  =  fCurrentGroupJast(); 
fCurrentGroup.remove(  fCurrentGroup.fromLastQ ); 
return  lastGroup; 

} 

void  Prefs::popAllGroups{) 

{ 

fCurrentGroup.clearO; 

} 

GroupElement  *Prefs::getGroupElementTree()  const 

{ 

y/qDebug("\nPrefs::getGroupElementTree()’'); 

GroupElement  ‘root  =  new  GroupElement("",  OL); 
QDictlterator<PrefsElement>  dictiter  (fEntryDict); 

PrefsElement  ‘curPrefsElement; 

VarElement*  aVarElement; 
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GroupElement  ‘insert!  nto; 

QStringList  groupList; 

QString  varName="'‘; 

for  {dictlter.toFirst();djctlter.current();++dlctlter) 

{ 

curPrefsElement  =  dictlter.current(); 

//qDebug("\ncreatlng  entry  for  key  :  dictlter.currentKey().ascii()): 

//  find  which  group  to  Insert  the  var  entry,  first  check  root 
if  (dictIter.currentKeyO.isEmptyO) 
insertinto  =  root; 
else  //  check  existing  subgroups 
{ 

groupList  =  parseGroupVarString(dictlter.currentKey{),  true,  &varName); 
If  ((insertinto  =  root->findChild(  groupList ))  ==  OL) 

{ 

//qDebug("\n  creating  a  new  group  sub  tree"); 

//  create  a  new  group 

insertinto  =  rooL>_createGroupSubTree(  groupList ); 

} 

} 


//  insert  the  var  entry  into  the  existing  or  created  group 
aVarElement  =  new  VarElement(  curPrefsElement->getName() ); 
insertlnto->_addVarElement  ( aVarElement ); 

) 

return  root; 

} 

QString  Prefs::createGroupVarString(const  QStringList  &strList) 

{ 

QString  g  = 

QStringList:  iConstIterator  Iter  =  strList,begin{); 
for  (int  i=0;iter  !=  strList.end();++lter,  i++) 

{ 

if  (i  >  0) 
g+=  V: 
g  +=  *iter; 

} 

return  g; 

} 

QString  Prefs::getCurrentGroup()  const 

{ 

return  createGroupVarString(fCurrentGroup): 

} 

bool  Prefs:;exists(const  QString  SvarName,  QString  group)  const 
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{ 

QString  key  =  _getKey(group,  varName); 

PrefsElement  ‘aValuePtr  =  fEntryDict.find(  key ); 
return  (aValuePtr  !=  OL); 

} 

QStringList  Prefs::parseGroupVarString(const  QString  &formatedGroupString,  bool  lastTokenIsVar,  QString 
•varName) 

{ 

QStringList  groupList; 

StringTokenizer  tokenizer(formatedGroupString, 

Tokenlteratortokenlter(tokenizer); 

int  lastToken  =  tokenizer.numTokens()-1; 
if  (llastTokenIsVar) 
lastToken++: 

for  (:tokenlter.getCurTokenNum()  <  lastToken:tokenlter++) 
groupList  +=  *tokenlter; 
bool  canStore  =  (varName  !=  OL); 
if  (canStore  &&  (tokenlter.isValid())) 

•varName  =  •tokeniter, 
return  groupList; 

} 

Appendix  A.03  -  Property.!! 

#ifndef  CPL_PROPERTY_H 
#define  CPL_PROPERTY_H 

/**************************************************************************** 


Classification:  UNCLASSIFIED  ***** 

*****  Classified  By: 

Declassify  On:  ***** 

#★***  ***** 

**************************************************************************** 


*  Developed  by:  Naval  Reseapp  Laboratory,  Tactical  Electronic  Warfare  Div. 

*  Effectiveness  of  Navy  Electronic  Warfare  Systems,  Code  5707 

*  4555  Overlook  Ave. 

*  Washington,  D.C.  20375-5339 

* 

•  For  more  information  please  call  202-767-2897  or  send  email  to 

•  enews@ene\ws.nrl.navy.mil 

• 

•  The  U.S.  Government  retains  all  rights  to  use,  duplicate,  distribute, 

•  disclose,  or  release  this  software. 

•/ 


40 


#inclucle  <qstrjng.h> 

#jnclude  <qtextstream.h> 

#include  <qdatastream.h> 

#include  <typeinfo> 

#inc!ude  "ConvertException.h" 

#include  "CPL/Convert/Converter.h'* 

#jnclude  "CPL/Convert/ConverterFactory.h’' 

#include  “CPLyCPLGIobaLh" 

#include  “Converter.h" 

r 

*  This  class  is  a  simple  templated  class  that  uses  rtti  to  allow  storage  of  any 

*  type,  while  at  the  same  time  maintaining  type  safety, 

* 

*  For  CORBA  people:  It  is  a  poor  mans  CORBA::Any. 

V 

If  PropertyDataHolder  (internal  class)  // 

class  DataHolder 

{ 

public: 

virtual  ~DataHolder()  { } 

virtual  void  get(void  *data,  const  std::typeJnfo&  tinfo)  const=0; 

virtual  const  std::type_info  &type!nfo()const=0: 
virtual  DataHolder  *clone()  const=0; 

}; 


template  <class  type> 
class  TypedDataHolder :  public  DataHolder 
{ 

public : 

TypedDataHolder(const  type  data,  const  std::typeJnfo&  tinfo) : 
fData(data),  fTypelnfo(tinfo) 

{ 

if  (typeid(fData)  !=  tinfo) 

throw  PropertyTypeMismatchException(TypedDataHolder(data,  info)",  fTypelnfo.name(), 

tinfo.nameO); 

) 

-TypedDataHolderO 

{ 
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//cout « 'deleting  TypedDataHolder* «  endl; 

} 

void  get(void  'data,  const  std:;typeJnfo&  tinfo)  const 

{ 

if  (tinfo  !=  fTypeInfo) 

throw  PropertyTypeMismatchException(“get",  fTypelnfo.name(),  tinfo.nameO); 

type  *typedParam  =  (type  ^)data; 

*typedParam  =  fData; 

} 

const  std::typeJnfo  &typelnfo{)  const  { return  fTypeInfo; } 

DataHolder  *clone()  const 

{ 

return  newTypedDataHolder<type>(fData,  fTypeInfo); 

} 


private : 
type  fData; 

const  std::typeJnfo&  fTypeInfo; 

}; 


H  Property  // 

class  Property 

{ 

public: 

/**  This  constructor  requires  a  value  to  ensure  that  the  property  is  instantiated 

*  correctly.  Sets  the  value  of  this  property.  If  an  invalid  type  is  given,  this  method 

*  will  throw  a  PropertyInvalidTypeException  whcih  will  contain  the  names  of  the  two 

*  types  that  the  property  was  trying  to  deal  with.  If  an  exception  is  thrown,  the 

*  Property  will  be  left  in  an  invalid  state.  It  is  recommended  that  you  destroy  the 

*  Property  in  a  catch  statement. 

V 

template  <class  type> 

Property  (const  type  t,  const  std::typeJnfo&  tinfo) :  fDataHolder(  OL ) 

{ 

set(t,  tinfo); 

} 

Property(const  Property  &copyFrom) :  fDataHolder(OL) 

{ 

DataHolder  *copy  =  copyFrom.fDataHolden 
if  (copy) 

copy  =  copy->clone(); 
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fDataHolder  =  copy; 

} 

r*  Default  constructor.  Allows  you  create  Property  objects  and  fill  the  value  in  later 

*  using  the  set  method.  If  get  is  called  before  set,  a  PropertyEmptyException  will 

*  be  thrown 
V 

PropertyO  :  fDataHolder(  OL ) 

{} 


-PropertyO 

{ 

if  (fDataHolder) 

delete  fDataHolder; 
fDataHolder  =  OL; 

} 

/*  Sets  the  value  of  this  property.  If  an  invalid  type  is  given,  this  method  will  throw 

*  PropertyInvalidTypeException  which  will  contain  the  names  of  the  two  types  that 

*  the  property  was  trying  to  deal  with.  If  an  exception  is  thrown,  the  Property  will 

*  be  left  in  an  invalid  state.  It  is  recommended  that  you  destroy  the  property  in  a 

*  catch  statement. 

V 

template  <class  typo 

void  set(const  type  t,  const  std::type_info&  tinfo) 

{ 

if  (tinfo  !=  typeid(t)) 

throw  PropertyTypeMismatchExceptionOset",  typeid{t).name().  tinfo.name()); 
delete  fDataHolder; 

fDataHolder  =  (DataHolder  *)new  TypedDataHolder<type>(t,  tinfo); 

} 

/**  Gets  the  value  back  from  the  property.  If  an  invalid  type  is  given,  this  method 

*  will  throw  a  PropertyTypeMismatchException  which  will  contain  the  names  of  the  two 

*  types  that  the  property  was  trying  to  deal  with.  The  original  value  should 

*  still  be  valid  in  the  propertyeven  if  an  exception  is  thrown 

V 

template  <class  type> 

void  get(type&  t,  const  std::type_info&  tinfo)  const 

{ 

if  (tinfo  !=  typeid(t)) 

throw  PropertyTypeMismatchExceptionCger,  typeid(t).name(),  tinfo.nameO); 
if  (IfDataHolder) 

throw  PropertyEmptyExceptlon(*’Propery::get''); 
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fDataHolder->get((void  *)&t,  tinfo); 

} 

virtual  Property&  operator=(const  Property  &copyFrom) 

{ 

DataHolder  *copy  =  copyFrom.fDataHolder; 
if  (copy) 

copy  =  copy->clone(); 
delete  fDataHolder; 

fDataHolder  =  copy; 
return  *this; 

} 

r*  Returns  the  type  info  for  this  type.  Will  throw  a  PropertyEmptyException  if  there 
*  is  no  type  in  this  property 

V 

virtual  const  std::typeJnfo&  getTypelnfo() 

{ 

if  (IfDataHolder) 

throw  PropertyEmptyException{"Property::getTypelnfo’‘); 

return  fDataHolder->typelnfo(); 

} 

/**  Returns  the  converter  for  this  property  using  the  ConverterFactory 

V 

virtual  Converter&  getConverter()  const 

{ 

if  (IfDataHolder) 

throw  PropertyEmptyException(Troperty::getConverter"); 

return  ConverterFactory::instance(),getConverter(  fDataHolder->typelnfo() ); 

} 

/**  Returns  the  converter  for  this  property  using  the  given  converter 

V 

virtual  Converters  getConverter(AbstractConverterFactory&  factory)  const 

{ 

if  (IfDataHolder) 

throw  PropertyEmptyException(Troperty::getConverter'*); 

return  factory.getConverter(  fDataHolder«>typelnfo() ); 

} 

protected: 
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DataHolder*  fDataHolder; 

}: 


#endif 

Appendix  A.04  -  Convertenh 

#lfndef  CPL^CONVERTER_H_ 

#define  CPL_CONVERTER_H_ 

#include  <qarray.h> 

#include  <qwjdget.h> 

#lnclude  <qstrjng.h> 

#include  <qsizepolicy.h> 

#include  <typelnfo> 

#include  -CPLyCPLGIobal.h" 

#lnclude  “ConvertException.h" 

#include  Troperty.h’* 

class  ConverterWidget; 

class  Converter 

{ 

friend  class  ConverterFactory; 
public: 

ConverterO  {}; 

/**  Takes  an  ascii  ByteArray  and  parses  it  into  something  valid,  then  returns  it  in  a 

*  property.  It  Is  the  callers  job  to  free  the  property.  Could  throw  a 

*  ConverterDataFormatException 

V 

virtual  Property*  fromAscii{const  QString)  =  0; 

/**  Takes  an  binary  ByteArray  and  parses  it  into  something  valid,  then  returns  it  in 

*  a  property.  It  is  the  callers  job  to  free  the  property.  Could  throw  a 

*  ConverterDataFormatException 

*/ 

virtual  Property*  fromBlnary(const  QByteArray)  =  0; 

/**  Takes  a  QWidget  and  uses  the  data  in  it  to  create  a  valid  Property,  returns  the 
*  property.  It  is  the  callers  job  to  free  the  property  and  the  QWidget  after  the 

*  function  call.  Could  throw  a  ConverterDataFormatException. 

*/ 

virtual  Property*  fromGUI(const  ConverterWidget&)  =  0; 

/**  Takes  an  ascii  QString  and  parses  it  into  something  valid,  then  fills  In  the  given 

*  property.  Could  throw  a  ConverterDataFormatException 
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V 

void  fromAscii(const  QString,  Property&  prop); 

r*  Takes  an  binary  Byte  Array  and  parses  it  into  something  valid,  then  fills  in  the 

*  given  property.  Could  throw  a  ConverterDataFormatException 

V 

void  fromBinary(const  QByteArray,  Property&  prop); 

/**  Takes  a  QWidget  and  uses  the  data  in  it  to  fill  in  the  given  property. 

*  Could  throw  a  ConverterDataFormatException 

V 

void  fromGUI(const  ConverterWidget&,  Property&  prop); 

/**  Takes  a  property,  encodes  it,  and  returns  the  value  in  a  ByteArray.  to  get 

*  This  method  needs  the  value  out  of  the  property  and  therefore  could  trigger  a 

*  PropertyTypeMismatchException 

V 

virtual  QString  toAsclj(const  Property&)  const  =  0; 

/**  Takes  a  property,  encodes  it,  and  returns  the  value  In  a  ByteArray.  This  method 

*  needs  to  get  the  value  out  of  the  property  and  therefore  could  trigger  a 

*  PropertyTypeMismatchException 

*/ 

virtual  QByteArray  toBinary(const  Property&)  const  =  0; 

r*  Takes  a  property,  creates  a  widget,  and  returns  the  widget  for  use  in  a  gui.  This 

*  method  needs  to  get  the  value  out  of  the  property  and  therefore  could  trigger  a 

**  PropertyTypeMismatchException 

V 

virtual  ConverterWidget*  toGU!(const  Property&,  QWidget*  parent  =  OL,  const  char*  name  =  OL)  const  =  0; 

r*  Returns  the  name  of  the  type,  like  Qlnt32  or  Qlnt16.  The  name  of  the  converter 

*  should  be  exactly  the  same  as  the  name  for  the  class,  minus  the  Converter.  For 

*  example:  BoolConverter  would  have  the  name  Bool 

*/ 

virtual  QString  typeName()  const  =  0; 

/**  Returns  the  typeinfo  for  the  type.  This  is  platform  dependent,  so  never 

*  store  this  value  past  the  end  of  the  program  execution  or  you  could  run  into 

*  problems  if  it  is  run  on  a  different  platform.  Just  use  this  method  for  simple 

*  comparisons. 

*/ 

virtual  const  std;:type_info&  typelnfo()  const  =  0; 
protected: 
private: 
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/**  ©link  dependency  V 
/*#  Property  InkProperty;  V 


}: 


class  ConverterWidget :  public  QWidget 

{ 

Q_OBJECT 

friend  class  Converter; 
public: 

~ConverterWidget()  {} 

/**  Returns  the  typeinfo  for  the  type.  This  is  platform  dependent,  so  never 

*  store  this  value  past  the  end  of  the  program  execution  or  you  could  run  into 

*  problems  if  it  Is  mn  on  a  different  platform.  Just  use  this  method  for  simple 

*  comparisons. 

V 

virtual  const  std::type_info&  typelnfo()  const  =  0; 

r*  Sets  the  display  of  this  widget  to  represent  the  given  property.  Could  throw  a 

*  PropertyTypeMismatchException  if  the  wrong  type  of  property  is  passed  in 
7 

virtual  void  setVaIue{const  Property&)  =  0; 

/**  Gets  the  value  out  of  the  widget  and  into  a  property.  It  is  the  callers  job 

*  to  free  the  property 
7 

virtual  Property*  getValue()  const  =  0; 

virtual  QSIzePolicy  sizePolicyO  const  { return  QSizePolicy(  QSizePoIicy::Preferred,  QSizePolicy::Preferred  ); } 
protected: 

ConverterWidget(QWidget*  parent  =  OL,  const  char*  name  =  OL) 

:  QWidget(parent,  name)  {} 

#define  signals  protected 
signals: 

void  modifiedO; 
protected  slots : 

void  slotModified(const  QString&)  { emit  modified(); } 
void  slotModified(lnt)  {  emit  modifiedO; } 
void  slotModifledO  {  emit  modifiedO; } 

}; 


#endif 
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Appendix  A.05  -  Qlnt32Converter.h 


#ifndef  CPL_QINT32_CONVERTER_H 
#define  CPL_QINT32_CONVERTER_H 

#include  "Converter.h" 


class  Property; 

/**  See  Converter.h  for  documentation 
V 

class  Qlnt32Converter :  public  Converter 

{ 

public: 

Qlnt32Converter(); 

virtual  QByteArray  toBinary(const  Property&  property)  const; 
virtual  QString  toAscii(const  Property&  property)  const; 

virtual  ConverterWidget*  toGUI(const  Property&,  QWidget*  parent  =  OL,  const  char*  name  =  OL)  const; 
virtual  Property*  fromAscil(const  QString  data); 
virtual  Property*  fromBinary(const  QByteArray); 
virtual  Property*  fromGUI{const  ConverterWldget&); 

virtual  QString  typeNameQ  const  { return  “Qlnt32"; } 

virtual  const  std::typeJnfo&  typelnfo()  const  { return  typeid(  Q_INT32  ); } 


}; 


class  QLIneEdit; 

class  CPL_EXPORT  Qlnt32ConverterWidget :  public  ConverterWidget 

{ 

friend  class  Qlnt32Converter: 
public: 

-Qlnt32ConverterWidget()  {} 

virtual  const  std::type_info&  typelnfo()  const  { return  typeid{  Q_INT32 ); } 

void  setValue(const  Property&); 

Property*  getValue()  const; 

protected: 

Qlnt32ConverterWidget(const  Property&  property,  QWidget*  parent  =  OL,  const  char*  name  =  OL); 
QLineEdit*  fValueEdIt; 

}; 
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#endif 


Appendix  A.06  ~  Qlnt32Converter.cpp 

#include  ‘’Qlnt32Converter.h'' 

#inc!ude  "Property.h" 

#include  <qlineedit.h> 

#include  <qlayout.h> 

#include  <typeinfo> 

Qlnt32Converter::Qlnt32Converter() 

{ 

} 

QByteArray  Qlnt32Converter::toBinary(const  Property&  )  const 

{ 

QByteArray  buffer; 

qDebug(''Qlnt32Converter::toBinary:  Not  implemented*'); 

return  buffer; 

} 

QString  Qlnt32Converter::toAscij(const  Property&  property)  const 

{ 

//  First  lets  get  the  value  from  the  property 
Q_INT32  value; 
property.get(value,  typelnfo()); 

return  QString::number(value);; 

} 

ConverterWidget*  Qlnt32Converter::toGUI(const  Proper1y&  property,  QWidget*  parent,  const  char*  name)  const 

{ 

//  Create  the  widget 

return  new  Qlnt32ConverterWidget(property,  parent,  name); 

} 

Property*  Qlnt32Converten:fromAscii(const  QString  data) 

{ 

bool  ok; 

QJNT32  number  =  data.tolnt(&ok); 
if  (lok) 

throw  ConverterDataFormatException(typeName()); 
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return  new  Property((  QJNT32  )number,  typeid(  Q_INT32 )); 

) 

Property*  Qlnt32Converten:fromBinary(const  QByteArray  data) 

{ 

qDebug(“Qlnt32Converter::fromBinary:  Not  implemented"); 

return  OL; 

} 

Property*  Qlnt32Converter.:fromGUI(const  ConverterWidgetS  widget) 

{ 

if  (widget.typelnfo()  !=  typeInfoO) 

throw  ConverterWidgetException(  typeName() ); 

return  widget.getValue(): 

} 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiim 
//  Qlnt32  CONVERTER  WIDGET 
lllllllllllllllllllllllllllllllllllllllllllllll^ 

Qlnt32ConverterWidget::Qlnt32ConverterWidget(const  Property&  property,  QWidget*  parent,  const  char*  name) 
:  ConverterWidget(parent,  name) 

{ 

QVBoxLayout*  layout  =  new  QVBoxLayout(this); 

fValueEdit  =  new  QUneEdit(this,  “fValueEdit"); 
fValueEdit->setMinimumSi2e(125,  fValueEdit->sizeHint().height()); 

connect(fValueEdit,  SIGNAL(  textChangedfconst  QString&) ),  SLOT(  slotModified(const  QStringa) )); 
layout->addWidget{  fValueEdit ); 

setMinimumSizef  fValueEdit->minimumSize() ); 

setValue(property); 

} 

void  Qlnt32ConverterWidget::setValue(const  Property&  property) 

{ 

fValueEdit->setText(ConverterFactory::instance().getConverter{  typelnfo()  ).toAscii(property)); 

} 

Property*  Qlnt32ConverterWidget::getValue()  const 

{ 

return  ConverterFactory::instance().getConverter(  typelnfof)  ).fromAscii(  fValueEdit->text() ); 

} 
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Appendix  A.07  -  QStringConverter.cpp 

#include  “QStringConverter.h" 

#include  "Property.h* 

#include  <qmultiljneedit.h> 

#include  <qlayout.h> 

#include  <typein(o> 

QStringConverter::QStringConverter() 

{ 

} 

QByteArray  QStringConverter::toBinary(const  Property&)  const 

{ 

QByteArray  buffer; 

qDebug("QStringConverter::toBjnary:  Not  Implemented"); 

return  buffer, 

} 

QStiing  QStringConverter::toAscii(const  Property&  property)  const 

{ 

//  First  lets  get  the  value  from  the  property 
QString  value; 

property,get(value,  typeInfoO); 

return  value; 

} 

ConverterWidget"  QStringConverter::toGUI{const  Property&  property,  QWidget*  parent,  const  char*  name)  const 

{ 

//  Create  the  widget 

return  new  QStringConverterWidget(property,  parent,  name); 

} 

Property*  QStringConverter::fromAscii(const  QString  data) 

{ 

Property  *prop  =  new  Property(data,  typelnfo()); 

return  prop; 

} 

Property*  QStringConverter::fromBinary(const  QByteArray  data) 

{ 

qDebug("QStringConverter::fromBinary:  Not  implemented'); 
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return  OL; 

} 

Property*  QStringConverten:fromGUI(const  ConverterWidgetS  widget) 

{ 

if  (widget.typelnfo()  !=  typeInfoO) 

throw  ConverterWidgetException(  typeName() ); 

return  widget.getValue(); 

} 

iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiim 
//  QSTRING  CONVERTER  WIDGET 
iiiiiiiiiiiiimiiiiiiiiiiiiiiiiiiiiiiiiiiim^ 

QStringConverterWidget::QStringConverterWidget{const  PropertyS  property,  QWidget*  parent,  const  char*  name) 
:  Convei1erWidget(parent,  name) 

{ 

QVBoxLayout*  layout  =  new  QVBoxLayout(  this ); 
fValueEdit  =  new  QMultiLineEdit(this,  "fValueEdit”); 
fValueEdit->setMinimumSize(1 25,  50); 

connect(fValueEdit,  SIGNAL(  textChanged() ),  SLOT(  slolModified{))): 
layout->addWidget(  fValueEdit ); 

setMinimumSize(  fValueEdit->minimumSize() ); 

setValue(property); 

} 

void  QStringConverterWidget::setValue(const  PropertyS  property) 

{ 

A/alueEdit->setText{ConverterFactory:;instance{).getConverter(typelnfo()  ).toAscii(property)); 

} 

Property*  QStringConverterWidget::getValue{)  const 

{ 

return  ConverterFactoty::instance().getConverter(  typelnfo()  ).fromAscii(  fValueEdit->text() );; 

} 

Appendix  A.08  -  SimplePrefsSerializer.h 

#ifndef  CPL_SIMPLEPREFSSERIALIZER_H 
#define  CPL_SIMPLEPREFSSERIALIZER_H 
#include  <qtextstream.h> 

#include  “PrefsSerializer.h" 

/********************♦******************************************************* 
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*****  Classification:  UNCLASSIFIED 

*****  Classified  By: 

*****  Declassify  On: 

*****  ***** 


*  $Source:  /enews/proj/spg/cvsroot/CPL/Prefs/SimplePrefsSerializer.h,v  $ 

*  $Author  mpilone  $ 

*  $Date:  2000/02/01  19:59:14$ 

*  $ld:  SimplePrefsSerializer.h.v  1.1. 1.1  2000/02/01  19:59:14  mpilone  Exp  $ 

* 

*  Developed  by:  Naval  Research  Laboratory,  Tactical  Electronic  Warfare  Div. 

Effectiveness  of  Navy  Electronic  Warfare  Systems,  Code  5707 

*  4555  Overlook  Ave. 

*  Washington,  D.C.  20375-5339 

* 

*  For  more  information  please  call  202-767-2897  or  send  email  to 

*  enews@enews.nrl.navy.mil 

* 

*  The  U.S.  Government  retains  all  rights  to  use,  duplicate,  distribute, 

*  disclose,  or  release  this  software. 

V 

/**  simply  loads  and  saves  a  prefs  class  to  and  from  a  text  io  device  (such  as  File) 
will  output  debug  statements  If  invalid  type  and  shouldThrowType  =  false 

V 

#lnclude  <qiodevlce.h> 

class  VarElement; 
class  GroupElement; 
class  Tokeniterator; 
class  Property; 
class  Converter; 

r 

*  This  class  provides  a  simple  serializer  that  will  dump  out  plain  text,  typesafe 

*  pref  files.  This  class  WILL  NOT  support  multiline  text.  If  you  need  to  save  multiline 

*  text  it  is  recommended  that  you  use  the  XMLPrefsSerializer  or  a  binary  serializer 

*  Caller  must  provide  a  prefs  for  this  class  to  use,  as  well  as  a  read/write  iodevice.  If  the 

*  io  device  is  a  file,  it  is  recommended  that  the  file  be  opened  with  the  truncate  option  so 

*  old  data  in  the  file  is  erased. 

V 

class  SimplePrefsSerializer :  public  PrefsSerlalizer 

{ 

public: 

SimplePrefsSerializerO; 
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/**  saves  prefs  into  a  io  device 

throws  lOException  or  ConverterllnsupportedException  upon  writing  error  V 
virtual  void  save(Prefs&  prefs,  QIODevice  &writableDevice); 

r*  parses  the  text  io  device  for  prefs  and  sets  them  into  the  current  prefs; 

note  that  this  will  just  ovenvrite  any  current  prefs,  but  also  keep  any  old  prefs  that 
aren't  overwritten;  user  must  reset  the  prefs  prior  to  load  for  the  prefs  to  contain 
only  what  is  in  the  io  device 

throws  lOException  or  ConverterUnsupportedException  upon  reading  error  V 
virtual  void  load(Prefs&  prefs,  QIODevice  &readabIeDevice); 

virtual  QString  typeName()  const  { return  "Simple"; } 

private: 

void  _saveEntry(Prefs&  prefs,  const  VarElement  &element,  const  GroupElement  &group); 
void  _recursiveSave(Prefs&  prefs,  GroupElement  *node); 

/**  Checks  for  C/C++  style  comments  and  returns  true  if  the  end  of  a  comment  was  found  or  *  no  comment 
found,  false  otherwise.  Continuation  means  that  the  line  being  passed  in  is 
*  still  inside  a  comment  that  was  started  on  a  previous  line.  The  caller  can  do  something  *  like:  <BR> 

*  continuation  =  LcutOutCommentArea(aLine,  continuation); 

V 

bool  _cutOutCommentArea(QString  &line,  bool  continuation  =  false); 

/**  parses  the  line  and  stores  the  information  in  the  prefs  class 

upon  error,  throws  InvalidFormatException  or  UnrecognizedTypeExceptionV 
void  _extractLine(Prefs&  prefs,  QString  line,  int  lineNum); 

/**@param  tokeniter  precondition:  tokeniter  at  the  group.varName  pos;  postcondition:  valid  iter  at  var  name  token 
extracts  the  group  from  the  tokens,  checking  for  correct  format; 
upon  error  thros  InvalidFormatException 
©return  the  group  string  V 

QString  _extractGroup(Tokenlterator  &tokenlter,  const  QString  &line,  const  int  lineNum); 

/**@param  tokeniter  precondition:  valid  token  at  the  name;  postcondition:  valid  token  at  "<"  delimiter 
extracts  the  name  from  the  tokens 
©return  the  name  V 

QString  _extractName(Tokenlterator  &tokenlter,  const  QString  &line,  const  int  lineNum); 

/**©param  tokeniter  precondition:  iter  at  delimiter  "<“;  postcondition:  valid  iter  one  token  past  ">" 
extracts  the  type  from  the  tokens,  checking  for  correct  format; 
upon  error  throws  InvalidFormatException 
©return  the  property  type  V 

QString  _extractType(Tokenlterator  &tokenlter,  const  QString  &!ine,  const  int  lineNum); 

/“©param  tokeniter  precondition:  valid  iter  after  delimiter  ">";  postcondition:  possibly 
invalid  iter  after  value  extracts  the  value  from  the  tokens,  checking  for  correct; 
format  upon  error  throws  InvalidFormatException 
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©return  the  property  type  */ 

Property*  _extractValue{Tokenlterator  Stokenlter,  Converters  converter,  const  QString  Sline,  const  int 
lineNum); 

QString  _extractDesc(Tokenlterator  Stokenlter,  const  QString  Sline,  const  int  lineNum); 

/**  all  parameters  must  be  in  correct  format  and  valid 
calls  the  appropriate  set  method  in  the  fPrefs  */ 

void  _setPrefs(Prefs&  prefs,  const  QString  SgroupName,  const  QString  SvarName,  Property*  value); 

void  _setPrefs(Prefs&  prefs,  const  QString  SgroupName,  const  QString  SvarName,  const  QString  &desc); 

QTextStream  fTextStream; 

QTextStream  fKeyValueStream; 

QTextStream  fDescStream; 

}: 


#endif  //  CPL_SIMPLEPREFSSERIALIZER_H 


Appendix  A.09  -  SimplePrefsSerializer.cpp 

#include  <qiodevice.h> 

#include  <qdatetime.h> 

#include  <qtextstream.h> 

#include  <qstringlist.h> 

#include  <qregexp.h> 

#include  <qbuffer.h> 

#include  "SimplePrefsSerializer.h" 

#include  Trefs.h’* 

#include  “VarElement.h" 

#include  "GroupElement.h" 

#include  “CPUConvert/Property.h" 

#include  “CPLyUtil/StringTokenizer.h" 

#include  "CPLyUtil/UtilException.h" 

SimplePrefsSerialjzer::SimplePrefsSerializer() : 

PrefsSeriallzerO 

{ 

} 

void  SimplePrefsSerializer::save(Prefs&  prefs,  QIODevice  &writableDevice) 

{ 

if  (IwiitableDevice.isWritableO) 

throw  lOException^Input/Output  device  is  not  writable"); 

QTextStream  outstream(&writableDevice); 
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GroupElement  ^groupRoot  =  prefs.getGroupElementTree(); 


outstream  «  _createFirstLineC)fFile(); 
outstream  «  r**********^***** 
outstream  « "  *  Written  by  cpI/prefs/Prefs  on " «  QDate::currentDate().toString()r 
outstream  « "  at " «  QTime::currentTime().toString()  «  *^n"; 
outstream  « »********♦******************************************************/"• 


//  Setup  the  test  streams  that  will  be  used 
QBuffer  ‘buffer  =  new  QBuffer, 
buffer->open(IO_WriteOnIy); 
fKeyValueStream.setDevice(  buffer ); 
buffer  =  new  QBuffer; 
buffer->open(iO_WriteOnly); 
fDescStream.setDevice(  buffer ); 


recurslveSave(prefs,  groupRoot); 


outstream  «  “\n\n/**=-=-=-=-=-=-=-[  KEY  /  VALUE  PAIRS 
buffer  =  (QBuffer*)(fKeyValueStream.device()); 
fKeyValueStream.unsetDeviceO; 

_checkStatus(outstream.device()); 

outstream.writeRawBytes(buffer->buffer().data(),  buffer->size()); 
delete(  buffer ); 

outstream  «  “\n\n/**=-=-=-=>=-[  DESCRIPTIONS  (DO  NOT  EDIT) 
buffer  =  (QBuffer*)(fDescStream.device()); 
fDescStream.unsetDeviceO; 

_checkStatus(outstream.device()); 

outstream.writeRawBytes(buffer->buffer().data(),  buffer->size()); 
delete(  buffer ); 

//  check  to  make  sure  io  device  is  still  valid 
_checkStatus(outstream.device()); 

//  Make  sure  we  leave  room  at  the  end  of  the  last  entry 
outstream  «  endl; 

} 

void  SimplePrefsSerializen:_saveEntry(Prefs&  prefs,  const  VarElement  &entry,  const  GroupElement  &group) 

{ 

// 1 )  create  the  string  to  save 

QString  groupName  =  group.getFullGroupName(); 


QString  keyValueUne  = 
QString  descUne  = 
QString  entryLine  =  '"‘i 
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if  (IgroupName.isEmptyO) 

{ 

entryUne  +=  groupName; 
entryLine  += 

} 


try{ 

//  lets  get  the  property  now  that  we  have  the  group  name  and  all 
const  Property&  prop  =  prefs.getProperty(entry.getName(),  groupName); 

entryLine  +=  entry,getName(); 
entryLine  += 

keyValueLine  =  entryLine  +  prop.getConverter().typeName{): 
descLIne  =  entryLine  +  "Description"; 
keyValueLine  +=  ">="; 
descLine  +=  ">="; 

//  2)  create  the  appropriate  key/value  line 
keyValueLine  +=  prop.getConverter().toAscii(  prop  ); 
keyValueLine  =  keyValueLine.replace(  QRegExp(“\\n"), 

//  3)  Create  the  description  line 

const  QString  desc  =  prefs.getDesc(entry.getName(),  groupName); 
if  (desc  !=  QString::null) 

{ 

descLine  +=  desc; 

descLine  =  descLine. replace(  QRegExpC'Wn"),  "-^/o-*"); 

} 

else 

descLine  =  QString:;null; 

//  4)  save 

fKeyValueStream  « 'W  «  keyValueLine ; 

if  (descLine  !=  QString::null) 

{ 

//qDebug("Writing  desc"); 
fDescStream  « '\n' «  descLine; 

} 

} 

catch  (Exception  e) 

{ 

qDebug("SimplePrefsSerializer::_saveEntry:  %s“.  e.toString().ascii()): 

} 

) 


57 


void  SimpIePrefsSerializen:_recursiveSave(Prefs&  prefs,  GroupElement  ‘node) 

{ 

//  save  all  entries  in  this  node 

//  qDebug("saving  Entries  for  group  ‘%s'".  node->getFullGroupName().ascii()): 
for  (QListlterator<VarElement>  entrylter  =  node->getVarEntrylterator():entiylter.current():  -H-entrylter) 
_saveEnfry(prefs,  *entrylter.currenf(),  ‘node); 

//  save  all  children 

for  (QListlterator<GroupElement>  childrenlter  =  node->getSubgrouplterator():childrenlter.current(); 
++childrenlter) 

_recursiveSave(prefs,  childrenlter.currentO); 

} 

bool  SimplePrefsSerializer.:_cutOutCommentArea(QString  &line.  bool  continuation) 

{ 

int  endCommentPos; 
int  startCommentPos; 

if  (continuation) 

{ 

//  Keep  going  until  we  find  a  close  comment 
if  ((endCommentPos  =  line.find("*/“))  !=  -1) 

{ 

line  =  line.right(  line.length()  -  endCommentPos  -  2);  //  subtract  2  for  the  size  fo  the  */ 
return  true; 

} 

else 

{ 

line  = 

return  false; 

} 

) 

else  if  ((startCommentPos  =  line.find(“/*“))  !=  -1)  //  Found  C  style  comment 

{ 

if  ((endCommentPos  =  line.find("*/“,  startCommentPos))  !=  -1) 

{ 

QString  tempLine; 

tempLine  =  line.left(startCommentPos); 

tempLine  +=  line.right(line.length()  -  endCommentPos-2);//  subtract  2  for  the  size  fo  the  ‘/ 
line  =  tempLine; 
return  true; 

} 

else 

{ 

line  =  line.left(startCommentPos); 
return  false; 

} 
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} 

else  if  ((startCommentPos  =  line.find(7r))  !=  -1)  //  Found  C++  style  comment 

{ 

line  =  line.left(startCommentPos); 
return  true; 

} 

return  true; 

} 

void  SimpIePrefsSerializer::load{Prefs&  prefs,  QIODevice  &readableDevice) 

{ 

bool  continuation  =  false; 

if  (IreadableDevice.isReadableQ) 

throw  IOException('‘lnput/Output  device  is  not  readable"); 

QTextStream  instream(  &readableDevice ); 

QString  curLine; 

int  lineNum=0; 

while  (linstream.atEndO) 

{ 

_checkStatus(instream.device()); 
curLine  =  instream.readLine(); 
lineNum++; 

continuation  =  LcutOutCommentArea(curLine,  continuation); 

if  (IcurLine.isEmptyO) 

_extractLine(prefs,  curLine,  lineNum); 

} 

} 

/**  parses  the  line  and  stores  the  information  In  the  prefs  class 
upon  error,  throws  PrefsInvalidFormatException  or  UnrecognizedTypeExceptionV 
void  SimplePrefsSeriallzer::_extractLine(Prefs&  prefs,  QString  line,  int  lineNum) 

{ 

StringTokenizer  tokenizer(line,  ".<>{},=",  true); 

Tokeniterator  tokenlter(tokeni2er,  true); 

//qDebug("SimpIePrefsSerializer::_extractLine:  Tokens  In  line:"); 

//for  (int  i  =  0;  i  <  tokenlter.numTokens();  i++) 

//qDebug("\tToken  [%d]:  %s",  i,  tokenlter[i].ascii{)); 

try{ 

tokenIter.toFirstO;  //  will  throw  exception  if  no  tokens 
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QString  group  =  _extractGroup(tokenlter.  line,  lineNum); 

QStiing  name  =  _extractName(tokenlter,  line,  lineNum); 

QString  type  =  _extractType(tokenlter,  line,  lineNum); 

//  Check  If  it  is  a  description 
if  (type  ==  "Description'*) 

{ 

QString  desc  =  _extractDesc(tokenlter,  line,  lineNum); 

_setPrefs(prefs,  group,  name,  desc); 

} 

else  //  It  is  a  key/value  pair 

{ 

Property  *value  =  _extractVaIue(tokenlter,  ConverterFactory::instance().getConverter(  type ),  line, 
lineNum); 

_setPrefs(prefs,  group,  name,  value): 

} 

} 

catch  (TokenIteratorInvalidRangeException  invalidRangeException) 

{ 

throw  PrefslnvalidFormatException(line,  lineNum); 

} 

} 

/**@param  tokeniter  precondition:  tokeniter  at  the  group. varName  pos;  postcondition:  valid  iter  at  var  name  token 
extracts  the  group  from  the  tokens,  checking  for  correct  format; 
upon  error  thros  PrefsInvalidFormatException 
©return  the  group  string  7 

QString  SlmplePrefsSerializer::_extractGroup(Tokenlterator  &tokenlter,  const  QString  &line,  const  int  lineNum) 

{ 

QString  fullGroup="‘'; 

QString  aGroup; 

//  iterate  through  the  tokens  until  find  the  <,  which  signifies  the  type  bracket 
while  (tokenlter[tokenltergetCurTokenNum()+1]  !=  "<") 

{ 

if  (IfullGroup.isEmptyO) 

fullGroup  += //  assign  a  dot  separator  if  not  the  first  group 

aGroup  =  ‘tokeniter;  //  assign  the  group 
fullGroup  +=  aGroup; 

++tokenlter;  //  move  to  the  next  delimiter 

//  if  the  next  token  isn't  a  valid  delimiter  or  this  isn't  the  correct  delimiter,  throw  format  exception 
if  (‘tokeniter  != ".") 


60 


throw  PrefslnvalidFormatException(line,  lineNum); 


++tokenlter;  //  move  past  the  group  seperator  (.  delimiter) 

} 

return  fullGroup; 

} 

/**@param  tokeniter  precondition:  valid  token  at  the  name;  postcondition:  valid  token  at  "<"  delimtiter 
extracts  the  name  from  the  tokens 
©return  the  name  V 

QString  SjmplePrefsSerializer::_extractName(Tokenlterator  &tokenlter,  const  QString  &line,  const  int  lineNum) 

{ 

QString  name  =  ‘tokeniter; 

++tokenlter; 
if  (‘tokeniter  !=  "<") 

throw  Prefslnva!idFormatException(line,  lineNum); 
return  name; 

} 

/“©param  tokeniter  precondition:  iter  at  delimiter  postcondition:  valid  iter  one  token  past  the  operator 
extracts  the  type  from  the  tokens,  checking  for  correct  format; 
upon  error  throws  InvalidFormatException 
©return  the  property  type  */ 

QString  SimpIePrefsSerializer::_extractType(Tokenlterator  &tokenlter,  const  QString  &line,  const  int  lineNum) 

{ 

//  move  passed  the  < 

++tokenlter; 

//  extract  the  type  name 

QString  propertyName  =  ‘tokeniter; 

propertyName  =  propertyName.stripWhiteSpace(); 

//  move  to  the  >  delim 

++tokenlter; 

if  (‘tokeniter  !=  ">") 

throw  PrefslnvalidFormatException(line,  lineNum); 

//  move  passed  the  >  delim 
++tokenlter; 

//  the  token;  should  be  delimiter  or  possibly  some  white  space 
QString  equalDelim  =  ‘tokeniter; 
equalDelim  =  equalDelim.stripWhiteSpace(); 
if  (equalDelim.isEmptyO  ||  equalDeIim.isNull()) 

{ 

tokenlter++; 
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equalDelim  =  *tokenlter; 

) 

//qDebug("finished  extracting  type,  getting  equal  delim  ‘%s'*,  equalDelim.ascii()): 
if  (equalDelim  !=  ’=") 

throw  PrefslnvalidFormatException(line,  lineNum); 

return  propertyName; 

} 

r*@param  tokenlter  precondition:  valid  iter  at  token  delim  postcondition:  possibly  invalid  Iter  after  value 
extracts  the  value  from  the  tokens,  checking  for  correct  format; 
upon  error  throws  PrefsInvalidFormatException 
@  return  the  property  type  V 

Property*  SimplePrefsSerializer::_extractValue(Tokenlterator  &tokenlter,  Converters  converter,  const  QString 
Sline,  const  int  lineNum) 

{ 

//  Extract  description  gets  all  the  tokens  after  the  '='  and  assembles  them 
//  into  one  long  string.  That  is  exactly  what  we  would  need  to  do  here,  so  we 
//  will  just  call  that  method 

return  converter.fromAscii(  _extractDesc(tokenlter,  line,  lineNum) ); 

} 

QString  SimplePrefsSerializer::_extractDesc(Tokenlterator  Stokenlter,  const  QString  &,  const  int) 

{ 

//  move  passed  the  equals  operator 
tokenlter++; 

QString  valueString  = 

//debug("Creating  string:"); 

Int  i  =  tokenlter.getCurTokenNumQ; 
while  (i  <  tokenIter.numTokensO) 

{ 

//qDebug("\tAdding:  %s’',  (*tokenlter).ascii()); 

valuestring  +=  tokenlter[i]; 

i++; 

} 

return  valueString.replace(  QRegExp("~%-''),  “Xn");; 

} 

/**  all  parameters  must  be  in  correct  format  and  valid 
calls  the  appropriate  set  method  in  the  fPrefs  */ 

void  SimplePrefsSerializer::_setPrefs(Prefs&  prefs,  const  QString  &group,  const  QString  &varName,  Property 
*value) 

{ 

//qDebug(*‘SimplePrefsSerializen:_setPrefs:  Name:  %s,  Group:  %s",  varName.ascii().  group.asciiQ); 
prefs.setProperty(varName,  value,  group); 
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} 


void  SimplePrefsSerializer:_setPrefs(Prefs&  profs,  const  QString  &group,  const  QString  &varName,  const  QString 
&desc) 

{ 

prefs.setDesc(varName,  dose,  group): 

} 

Appendix  A.10  -  PrefsEditor.h 

#ifndef  _PREFS_EDITOR_H 
#define  _PREFS_EDITOR_H 
#inclucle  <qwiclget.h> 


Classification:  UNCLASSIFIED 
Classified  By: 

Declassify  On: 


*  $Source:  /enews/proj/spg/cvsroot/CPL/GUIAA/idgets/PrefsEditor.h,v  $ 

*  $Author:  mpilone  $ 

*  $Date:  2000/02/01  19:59:13$ 

*  $ld:  PrefsEditor.h, V  1.1. 1.1  2000/02/01  19:59:13  mpilone  Exp  $ 

* 

*  Developed  by:  Naval  Research  Laboratory,  Tactical  Electronic  Warfare  Div. 

*  Effectiveness  of  Navy  Electronic  Warfare  Systems,  Code  5707 

*  4555  Overlook  Ave. 

*  Washington,  D.C.  20375-5339 

* 

*  For  more  information  please  call  202-767-2897  or  send  email  to 

*  enews@enews.nr1.navy.mil 
« 

*  The  U.S.  Government  retains  all  rights  to  use,  duplicate,  distribute, 

*  disclose,  or  release  this  software. 

V 

class  Prefs; 
class  Property; 
class  ConverterWidget; 
class  GroupElement; 
class  VarElement; 
class  QListView; 
class  QListViewItem; 
class  QSplitter; 
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class  QLabel; 
class  QScrollView; 
class  QVBoxLayout; 

//class  QVBox; 

class  CPL.EXPORT  PrefsEditor :  public  QWidget 

{ 

Q.OBJECT 
public ; 

PrefsEditor(QWidget  ‘parent,  const  char  ‘name); 
virtual  ~PrefsEditor(); 

void  setPrefs(Prefs  &prefs); 

Prefs  &getPrefs()  const  { return  ‘fPrefs; } 

const  QListView  &getGroupTree{)  { return  ‘fGroupTree; } 
const  QListView  &getVarList{)  { return  ‘fVarList; } 

bool  isPrefsModifiedO  const  { return  fPrefsModified; } 

void  setPrefsModified(bool  v)  { fPrefsModified  =  v;  emit  prefsModified(fPrefsModified): } 
void  storeCurrentPropertyFromGUIO; 

signals: 

void  prefsModified(bool  v); 
protected  slots: 

void  slotUpdateVarDisplay(QListViewltem  ‘groupTreeSelected); 
void  slotUpdateValueEditorWidget(QListViewltem  ‘varltemSelected); 
void  slotPropertyModifiedO; 

/“Oparam  selectVar  may  be  null 

designed  to  connect  with  PrefsFindDialog  goButtonClicked,  but  could  work  with  others  ‘/ 
void  slotUpdateDisplay{GroupElement  ‘selectGroup,  VarElement  ‘selectVar); 

protected: 

static  QStringList_getGroupStringList{const  QListViewItem  ‘groupTreeSelected); 
const  Property  &_getValueEditorProperty(QListViewltem  ‘varltemSelected)  const; 
void  _setValueEditorWidget(const  Property  &p); 
void  _showNothingSelected(); 
void  _selectVarltem(const  QString  &text); 

private : 

void  _recursiveBuildGroupTree(GroupElement  ‘node,  QListViewItem  ‘parent); 

QListViewItem  ‘_openGroupTree(const  QList<GroupElement>  &branch); 

void  JnitPanesQ; 
void  JnitGroupT reePane();  * 
void  JnitVarListPaneO; 
void  JnitDescrValuePaneO; 
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void  _initConnectlons(); 

void  _setValueLabel(  QListViewItem  *varltem); 

/**  coordinates  switching  widget  editors  and  setting  the  property  values  V 
class  EditWidgetCoordinator 
{ 

public; 

r*  store  orig  property,  get  new  item  widget,  set  as  display  V 

EditWidgetCoordinator(PrefsEditor  ‘editor,  QListViewItem  ‘varltem,  QListViewItem  *groupltem); 
/**  remove  from  display  cur  widget  and  store  the  new  property  if  changed  V 
-EditWidgetCoordinatorO; 

/**  updates  the  editor->fDescr  text  with  the  prefs  desc  7 
void  showDescO; 

/**  gets  the  value  from  the  gui  and  stores  in  the  prefs  V 
void  storePropertyFromGuiO; 

/“  get  the  property  from  the  prefs  with  the  class  group.var  name  7 
const  Property  &getProperty(); 

ConverteiWidget  *getWidget()  { return  fWidget; } 

QListViewItem  *getVarltem()  { return  fVarltem; } 

QListViewItem  *getGroupltem()  { return  fGroupItem; } 
bool  isPropertyModifiedO  { return  fPropertyModified; ) 
void  setModified(bool  v)  { fPropertyModified  =  v; } 

private : 

PrefsEditor  ‘fEditor; 

QVBoxLayout  ‘fLayout; 

ConverterWidget  ‘fWidget; 

QListViewItem  ‘fVarltem; 

QListViewItem  ‘fGroupItem; 
bool  fPropertyModified; 

}; 

friend  class  EditWidgetCoordinator; 

EditWidgetCoordinator  ‘fEditWidgetCoordInator; 

QListView  ‘fGroupTree; 

GroupEIement  ‘fGroupRoot; 

QListView  ‘fVarList; 

QSplitter  ‘fVarValueSplitter; 

QSplitter  ‘fTreeVarSplitter; 

QLabel  ‘fDescrLabel; 
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QLabel  *fDescr; 

QLabel  'fValueLabel; 

//QScroIlView  MDesciValueScroll; 

QWidget  ‘fValueContainerWidget: 

QWidget  ‘fRightPanelWidget;  //contains  the  description  and  vaiue 

Prefs  ‘fPrefs; 

bool  fPrefsModified; 

}: 


#endif 


Appendix  A.11  -  PrefsEditor.cpp 

#include  "CPLyGUI/Widgets/PrefsEditor.h" 

#include  <qsplitter.h> 

#include  <qlabel.h> 

#include  <qljstview.h> 

#include  <qvbox.h> 

#include  <qscrollview.h> 

#include  <qlayout.h> 

#include  "CPL/Convert/Converter.h" 

#include  "CPLVConvert/Property.h" 

#include  "CPL/Prefs/Prefs.h" 

#include  "CPLyPrefs/GroupElement.h" 

#include  "CPiyPrefsA/arElement.h" 

#include  “CPL/Prefs/Prefs.h" 

PrefsEditor::PrefsEditor{QWIdget  ‘parent,  const  char  ‘name) :  QWidget(parent,  name),  fPrefsModifled(false), 
fPrefs(OL) 

{ 

JnitPanesO; 

JnitGroupT  reePane(); 

JnitVarLIstPaneO; 

JnitDescrValuePaneO; 

fEditWidgetCoordinator  =  OL; 

JnitConnectionsO; 

_showNothingSelected(); 

} 

Pref  sEditor: :  ~  Pref  sEditor() 

{ 

delete  fEditWidgetCoordinator; 
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} 


void  PrefsEditor.:JnitConneclions() 

{ 

QObject::connect(fGroupTree,  SIGNAL(  selectionChanged(  QListViewItem  *) ),  this,  SLOT( 
slotUpdateVarDjsplay(QListViewltem  *) )); 

QObject::connect(fVarList,  SIGNAL(  selectjonChanged(  QListViewItem  *) ),  this,  SLOT( 
slotUpdateValueEditorWidget(QLIstViewltem  *))); 

} 

void  PrefsEditor::_initPanes() 

{ 

fVarValueSplitter  =  new  QSplitter(this,  "fVarValueSplitter"); 
fVarValueSplitter->setOrientation(QSplitter::Horizontal); 

fTreeVarSpIitter  =  new  QSplitter(fVarValueSpIitter,  "fTreeVarSplittor"); 
frreeVarSplitter“>setOrientation(QSplitter::Vertical): 

fRightPanelWidget  =  new  QWidget(fVarValueSplitter,  "fRightPanelWidget”); 

QVBoxLayout  layout  =  new  QVBoxLayout(  this ); 
layout->addWidget(fVarValueSplitter); 

} 

void  PrefsEditor::  JnitGroupT reePane() 

{ 

fGroupTree  =  new  QListView{fTreeVarSpIitter,  "fGroupTree”); 
fGroupTree->addCoiumn(''Group''); 
fGroupT ree->addColumn{''#  Items"); 
fGroupTree->setMinimumSize(  110,  100); 

} 

void  PrefsEditor::JnitVarLjstPane() 

{ 

fVarList  =  new  QListView(fTreeVarSplitter,  "tVarLIst"); 
fVailist->addColumn('‘Name"); 
fVarList“>setMinimumSize(  110,  100); 

} 


void  PrefsEditor::_initDescrValuePane() 

{ 

QVBoxLayout  "layout  =  new  QVBoxLayout(fRightPanelWidget); 

fDescrLabel  =  new  QLabelC’Description",  fRightPanelWidget,  "fOescrLabel"); 
fDescrLabel->setFont(QFont{‘'Times‘',  14,  QFont::Bold)); 
fDescrLabel*>setAIignment(  QObject::AlignCenter ); 
fDescrLabeL>setMaximumHeight(  fDescrLabel->sizeHint().height() ); 
layout->addWidget(fDescrLabel); 
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fDescr=  new  QLabel(“".  fRightPanelWidget,  "fDescr"); 
fDescr->setFont{  QFontCTimes",  12,  QFont::Normal) ); 
fDescr->setAllgnment(  QObject::AlignCenter ); 
fDescr->setAutoResize(  true ); 
fDescr->setMinlmumSize(  100, 150); 
fDescr“>setMaxlmumHeight(  150 ); 
layout->addWidget(fDescr); 

QFrame  *|jneSeperator  =  new  QFrame(  fRightPanelWidget,  "descr/value  line  seperator"); 

lineSeperator->setFrameStyle  ( QFrame::HLine  |  QFrame::Sunken); 

lineSeperator->setLineWidth(  2 ); 

lineSeperator->setMidLineWldth(  1  ); 

lineSeperator->setFlxedHeight(  10 ); 

layout->addWidget(lineSeperator); 

fValueLabel  =  new  QLabeK^Value",  fRightPanelWidget,  "fValueLabel"); 
_setValueLabel(OL); 

fValueLabel>>setFont(  QFontC'times",  14.  QFont::Bold) ); 
fVaIueLabel->setAlignment(  QObject::AlignCenter ); 
fValueLabel->setMaximumHeight(  fValueLabel->sizeHint{).height() ); 
layout->addWldget(fVaIueLabei); 

fValueContainerWidget  =  new  QWidget{  fRightPanelWidget,  ‘'fValueContainerWidget"); 
layout->addWidget(fValueContainerWldget); 

} 

void  PrefsEditor::_setValueLabel(QListViewltem  *viewltem) 

{ 

QString  labe!="“; 
if  (viewitem) 

{ 

label  =  viewltem->text(0); 
label  += "  Value"; 

} 

else 

label  =  "No  Item  Selected"; 
fValueLabel->setText(  label ); 

} 

QStringList  PrefsEditor::_getGroupStringList(const  QListViewltem  *groupTreeSelected) 

{ 

QStringList  groupName; 

while  (group! reeSelected->parent()) 

{ 

groupName.insert{  groupName,begin(),  groupTreeSelected->text(0) ); 
groupTreeSelected  =  groupTreeSelected->parent(); 

} 
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return  groupName; 

} 


void  PrefsEditor::slotUpdateDlsplay(GroupElement  *selectGroup,  VarElement  ‘selectVar) 

{ 

QString  fullGroupName  =  selectGroup->getFuIIGroupName(),ascjl(); 

//if  (selectVar) 

//qDebug(‘‘PrefsEditor::slotUpdateDlsplay(%s,%s)",  fullGroupName.ascli(),  selectVa7->getName().ascji()); 
//  else 

//qDebug{TrefsEditor:slotUpdateDisplay(%s,  null )",  fullGroupName.ascli()); 

QList<GroupElement>  branch; 

fGroupRoot->findChild{Prefs;:parseGroupVarString(ful!GroupName, false),  &branch); 

//qDebugCXtbuilt  branch  from  tree;  branch  has  %d  nodes",  branch.count()); 

QListViewItem  "groupitem  =  _openGroupTree(branch); 
if  (groupitem) 

{ 

fGroupT  ree->setSelected(groupltem,  true); 
if  (selectVar) 

_selectVarltem(selectVar->getName{)); 


} 

void  PrefsEditor::_selectVarltem(const  QString  &text) 

{ 

bool  itemSelected=false; 

for  (QListViewItem  *varltem=fVarList->firstChild();varltem  &&  !itemSeIected;varItem=varltem->nextSibling()) 
if  (varltem->text(0)  ==  text) 

{ 

fVarLlst->setSelected(varltem.  true); 
itemSelected=true; 


} 

QListViewItem  *PrefsEditor::_openGroupTree(const  QLIst<GroupElement>  &branch) 

{ 

bool  itemOpened=true; 

QListViewItem  *childltemFound=OL; 

QListViewItem  *firstlnLevel=fGroupTree->firstChild(); 
if  (branch.countO  ==  0) 
return  firstlnLevel; 

firstInLevel=firstlnLevel->firstChild(); 

for  (QListlterator<GroupElement>  branchlter(branch);branchlter.current()  &&  itemOpened;++branchIter) 

{ 

itemOpened=false; 

//qDebug("\ttrying  to  open  tree  node  for  group  =  ‘%s'",branchlter.current()->getGroupName().ascli()); 
for  (QListViewItem  *groupltem=firstlnLevel;groupltem  &&  litemOpened;groupltem=groupltem- 
>nextSibIing()) 
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{ 

//qDebug{"\tcomparing  item  %s“,  groupltem->text(0).ascii()); 
if  (groupltem->fext(0)  =  branchlter.current()->getGroupName()) 

{ 

//qDebugCMopening  tree  node  =  '%s‘",  groupltem->text(0).ascii()); 
if  (childItemFound) 
childltemFound->setOpen(true): 
childltemFound=groupltem; 
firstlnLevel=childltemFound->firstChild(); 
itemOpened=true; 

} 

} 

} 

return  childItemFound; 

} 

void  PrefsEditor::slotUpdateVarDisplay(QListViewltem  *groupT reeSelected) 

{ 

//  delete  the  current  list 
fVarList->clear{); 

if  (group! reeSelected) 

{ 

QStringList  groupList  =  _getGroupStringList(groupTreeSelected); 
//qDebugCsIotUpdateVarDisplay;  building  var  list  for  group  '%s'”, 
Prefs::createGroupVarString(groupList).ascii()); 

H  get  the  node 

GroupElement  *groupNode  =  fGroupRoot->findChild(groupList); 

//  build  the  var  list  from  the  node 
VarElement  *aVarEntry; 

QListViewItem  *listltem; 

QListlterator<VarElement>  varlter  =  groupNode->getVarEntrylterator(): 
for  (varlter.toFirst();varlter.current():++varlter) 

{ 

aVarEntry  =  varlter.current(): 

//qDebug("\tadding  var  item  '%s",  aVarEntry->getName().ascii()); 
listltem  =  new  QListViewltem(fVarList,  aVarEntry- >getName(),  "iistitem"); 
listltem->setOpen(true); 

} 

//  select  an  item  in  the  fVarList 
fVarList->setSelected{  fVarList->firstChild(),  true); 

} 

} 

void  PrefsEditor;slotUpdateValueEditorWidget(QListViewltem‘varltemSelected) 

{ 
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//if  (varltemSelected) 

//qDebugCsIotUpdateValueEditorWidget  for  %s",  varltemSelected->text(0).ascij()); 

//  else 

//qDebugCsIotUpdateValueEditorWidget  for  <empty  ltem>''); 

delete  fEditWidgetCoordinator; 
fEditWidgetCoordinator  =  OL; 

_setValueLabel(  varltemSelected ); 
if  (varltemSelected) 

fEditWidgetCoordinator  =  new  EditWidgetCoordlnator(this,  varltemSelected,  fGroupTree->selectedltem()); 


} 

void  PrefsEditon:setPrefs(Prefs  &prefs) 

{ 

If  (fPrefs) 

{ 

fVarList->cIearSelection(); 
fGroupT  ree>>clearSelection(); 

delete  fGroupRoot; 
fGroupRoot  =  OL; 

) 

fPrefs  =  &prefs; 
fPrefsModified  =  false; 

//  reset  the  group  tree 
//qDebug(“setPrefs;  creating  group  list”); 
fGroupT  ree“>clear(); 

fGroupRoot  =  fPrefs->getGroupElementTree(); 

_recursiveBuildGroupTree(  fGroupRoot,  OL ); 

fGroupTree->setOpen(  fGroupTree->flrstChild(),  true); 

} 


void  PrefsEditor::_recursiveBuildGroupTree(GroupElement  *node,  QListViewItem  *parent) 

{ 

//  add  the  node  as  an  entry  in  the  tree 
QListViewItem  ‘listitem; 
if  (parent) 

listitem  =  new  QLIstViewltem(parent,  node->getGroupName(),  QString::number(node- 
>getVarEntrylterator().count())); 
else 

listitem  =  new  QListViewltem(fGroupTree,  “.(root)",  QString::number(fGroupRoot- 
>getVarEntrylterator().count())); 


71 


//qDebug("\tadded  item  '%s’  (full=%s)",  node->getGroupName().ascii(),  node->getFullGroupName().ascii()); 
//  build  the  tree  nodes  for  all  children  (ie  sub  groups) 

for  (QListlterator<GroupElement>  childreniter  =  node->getSubgrouplterator();childrenlter.current(): 
++childrenlter) 

_recursiveBuildGroupT ree(childrenlter.current(),  listitem); 

} 

void  PrefsEditor::slotProperfyModified() 

{ 

if  (fEditWidgetCoordinator) 

fEditWidgetCoordinator->setModified(true): 

setPrefsModified(true): 

} 

void  PrefsEditor::_showNothingSelected() 

{ 

fDescr->setText{”No  item  selected"); 

} 

void  PrefsEditor::storeCurrentProper1yFromGUI() 

{ 

if  (fEditWidgetCoordinator) 

fEditWidgetCoordinator->storePropertyFromGui(); 

) 

/**  add  the  widget  that  corresponds  to  the  selected  group, var  item  to  the  edit  widget  area  */ 
PrefsEditor::EditWidgetCoordinator;:EditWidgetCoordinator(PrefsEditor  "editor,  QListViewItem  "varltem, 
QListViewItem  "groupitem) ; 

fEditor(editor),  fVarltem(varltem),  fGroupltem(groupltem).  fPropertyModified(false) 

{ 

fLayout  =  new  QVBoxLayout(fEditor->fValueContainerWidget); 
fLayout->setMargin(  10 ); 

const  Property  &p  =  getPropertyO; 

fWidget  =  p.getConverter().toGUI(p,  fEditor->fValueContainerWidget.  “EditWidgetCoordinator;:fWidget"): 
fLayout->addWidget{fWidget); 

A/Vidget->show(); 

QObject:;connect(  fWidget,  SIGNAL(modified()),  fEditor,  SLOT(slotPropertyModified())); 

showDescO; 

} 

PrefsEditor:EditWidgetCoordinaton:-EditWidgetCoordinator() 
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{ 

//qDebugCdeleting  EditWidgetCoordinator  for  %s",  fVarltem->text(0).ascll()); 
storePropertyFromGulO; 

//qDebug('^tdisconnectlng''); 

QObject::disconnect(  fWidget,  SIGNAL(modjfied()),  fEditor,  SLOT(slotPropertyModified()) ); 

delete  fWidget; 

fWidget  =  OL; 

delete  fLayout; 

fLayout  =  OL; 

fEditor->_showNothlngSelected(); 

} 


void  PrefsEditor::EditWidgetCoordinator:showDesc() 

{ 

QString  groupStr  =  Prefs::createGroupVarString(  _getGroupStringList(  fGroupItem  ) ); 

QString  propertyName  =  fVarItem->text(0); 

QString  descr  =  fEditor->getPrefs().getDesc(  propertyName,  groupCtr ); 
if  (descr.isEmptyO  ||  descr.isNullO) 

fEditor->fDescr->setText{'*No  description"); 

else 

fEditor->fDescr->setText(  descr ); 

} 

const  Property  &PrefsEditor::EditWidgetCoordinator::getPropei1y() 

{ 

QString  groupStr  =  Prefs::createGroupVarString(  _getGroupStringList(  fGroupItem  ) ); 

QString  propertyName  =  fVarltem->text(0); 

return  fEditor-’>getPrefs().getProperty(  propertyName.  groupStr); 

} 

void  PrefsEditor::EditWidgetCoordinator::storeProper1yFromGui() 

{ 

try{ 

//qDebug("EditWidgetCoordinator::storePropertyFromGul{)"); 
if  (isPropertyModifiedO) 

{ 

//  gather  all  parameters  to  set  the  property  from  the  gui 
QString  propertyName  =  fVarltem->text(0); 

QString  groupstring  =  Prefs::createGroupVarString(  _getGroupStringLlst(  fGroupItem )); 
const  Property  &p  =  getProperty(); 

//qDebug("\tgathering  parameters;  property  name=%s\tgroup  string=%s'',  propertyName.ascii(), 
groupString.asciiQ); 

Property  *newProperty  =  p.getConverter().fromGUI(*fWidget); 

//qDebug("\tsettjng  property  %s.%s  =  %s",  groupString.ascii(),  propertyName.ascli(),  newProperty* 
>getConverter().toAscii(*newProperty).ascii()); 
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//  set  the  property 

fEditor->getPrefs0.setProperty(propertyName.  newProperty,  groupString); 

//  emit  signal  that  the  prefs  have  been  modified 
emit  fEditor->prefsModified(tme): 

//  reset  the  property  modified  flag 
fPropertyModified  =  false; 

} 

} 

catch  (Exception  e) 

{ 

qDebug(e.toString().ascii()); 

) 

} 
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